An open source design system that's fully customizable and agent ready
schema_version: 1 template_version: 1 kind: architecture id: architecture:knowledge-contracts authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-08-30 owners: [cixzhang] applies_to: [ AGENTS.md, .github/PULL_REQUEST_TEMPLATE/, .github/pull_request_template.md, .github/scripts/api-tagalong.mjs, docs/, packages/, ] verified_by: [ scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs, scripts/lib/review-diff.test.mjs, .github/scripts/change-scope.test.mjs, .github/scripts/component-design-decisions.test.mjs, .github/scripts/lib/classify-visual.test.mjs, .github/scripts/review-clear-workflow.test.mjs, .github/scripts/review-signal-decision.test.mjs, .github/scripts/review-signal-workflow.test.mjs, .github/scripts/spec-owner-decision.test.mjs, .github/scripts/api-tagalong.test.mjs, apps/docsite/src/tests/example-coverage.test.ts, ]
deciding_specs: []
Knowledge contracts and decisions
{
"scope": "global",
"triggers": {
"specification": [
"INV9",
"INV11",
"INV14",
"INV16",
"INV18",
"INV20",
"INV21",
"INV25",
"INV26",
"DEC-9",
"INV27",
"DEC-10",
"DEC-12",
"DEC-13",
"DEC-15",
"INV28",
"INV31"
]
}
}
{
"paths": ["apps/docsite/**"]
}
Purpose
A reviewer should be able to answer two questions without rereading old pull requests:
- What behavior has a human already decided?
- Is this pull request making a new decision that needs a human?
System model
Astryx keeps different facts in different places:
- Component contracts describe aggregate behavior one component promises.
- Module contracts describe an independently contractible public hook, plugin, utility, or subsystem owned by one component. Private implementation helpers do not require records.
- An optional
Design decisionstable inside a component or module contract records durable visual intent local to that owner. It does not hold exact pixel tuning or rules shared across components. - Family contracts describe behavior sibling components share.
- Design specs record human-owned visual and interaction decisions, including the cross-theme accessibility and contrast methodology used to judge token/color pairings.
- Theme specs record one package theme's intent, inherited base, selected token and palette mappings, required pairings/states, theme-specific exceptions, measured receipts, known gaps, compatibility, and artifacts.
- System specs record decisions that cross components or themes or change architecture.
- Consumer docs explain props, examples, and usage.
- Audit records hold current evidence and findings. The operational store is the
automated wiki
component-scores.json, which supplies the current post-fix score and unresolved findings to the sandbox. The bootstrap reserved colocated<PublicName>.audit.jsonfiles, but no schema or records activated that path; it is not an audit datastore or current migration target.
The reviewer starts with the changed code and the nearest current component or module contract. They follow only the links needed for the question:
changed code or theme source
→ nearest current component, module, or theme contract
→ relevant family or design requirement
→ architecture or system decision only when referenced
→ mapped tests and audit evidence
A lookup can also start from any repository path. pnpm specs:for <path>
lists every current record linked to that path, the system specs that decided
those records, and the global claims the path's component triggers route; with
--diff, the claims the change's concerns route come first (INV20). It
follows only links that records and files declare:
- placement: the record itself, the component, module, or theme record whose
canonical location contains the path (a component or module record's location
is the source directory its folder under
docs/specs/components/mirrors); - path fields:
applies_to,verified_by, andpath-applicability:v1patterns; - names: family
members, designcomponents, andaffects_consumer_docsids naming the path's component or consumer-doc topic; - citations: a system-spec number such as
AST-030, or a claim such asAST-108 FR4, written in the file's prose, such as a Markdown document. The lookup also reads one in a source comment, but INV29 moves each such link into a record before the comment is removed, so removing a comment never drops a file's only link to a record; - inheritance: the references a linked record relies on.
A current record may cite a previous human decision. When the new case is within that decision's stated scope, the reviewer applies it without asking again.
Theme records sit between shared theming architecture and downstream records. Cross-theme API, vocabulary, inheritance, validation, compiler behavior, and artifact policy remain in architecture or system specs. Cross-theme human visual and accessibility methodology for contrast belongs in a current design record; shared measurement/tool implementation belongs to architecture or tooling. One theme's selected token/palette mappings, required pairings and states, exceptions, measured receipts, known gaps, migration, and artifacts belong in its package-local theme record. Components and families continue to own observable behavior; consumer docs continue to own supported syntax and examples.
Every record is either:
draft: useful for review, but not a rule;current: explicitly approved and safe to rely on;archived: retained for history and linked to its replacement when one exists.
Boundaries and invariants
- INV1 — Current means approved. Only
currentrecords guide implementation and review. - INV2 — One fact has one owner. A component or theme record does not copy family, design, system, consumer, audit, or tooling content. Cross-theme API and compiler behavior stay in architecture/system records; human contrast methodology stays in design; shared measurement implementation stays in architecture/tooling; theme-specific mappings, states, exceptions, receipts, and gaps stay in the package-local theme record; aggregate observable component behavior stays in component/family records; independently contractible public component-module behavior stays in module records; consumer syntax stays in consumer docs.
- INV3 — Existing decisions are reusable. A reviewer cites an applicable decision and proceeds without asking the human again.
- INV4 — New judgment is explicit. A reviewer asks a human when no current decision applies, existing decisions conflict, or the choice is deliberately human-owned.
- INV5 — Blank forms are not policy. Templates only create drafts. Search and review never present template text as an approved Astryx decision.
- INV6 — Required structure changes per kind. Template wording may change without touching existing records. Adding a new kind does not migrate unrelated kinds. Adding or removing a required field or section from an existing kind creates a later schema definition for that kind and migrates every active record of that kind in the same pull request.
- INV7 — Only pure spec changes use lightweight CI. Every changed file must be a component, module, family, design, theme, or system spec. A change to code, architecture, guidance, templates, schemas, audits, or any unknown path runs normal CI.
- INV8 — Private operations stay private. Public records never name or link private release or automation systems.
- INV9 — Current records have no implicit precedence. A newer, narrower, or more local current record does not silently override another current record.
- INV10 — Records describe ideal behavior, not pull-request verdicts. A current record states durable requirements, prohibitions, compatibility, ownership, and evidence independently of any one implementation change. It never exists to approve a pull request and never approves, rejects, classifies, designates, or authorizes a specific one. Pull requests and issues are not standing content: a record states the fact a change established, not the change, and remains complete without any pull request or issue it once cited. Research that supports a decision — a survey, an options comparison, a benchmark, a test's design or scores — is an artifact linked from the pull request, not record content; the record keeps the conclusion inside the decision that rests on it. A fact owned elsewhere is delegated by linking the record that owns it. The reviewer owns each change's disposition against current authority.
- INV11 — Every public delta has an authority result. Every public API update and every public behavior change is matched to current committed authority before acceptance. Package-export shape is not the only trigger: reachable supporting types, context members, hook returns, defaults, and observable behavior participate too.
- INV12 — Audit state has one automated datastore. Wiki
component-scores.jsonis the operational source for current scores and unresolved findings. The unactivated<PublicName>.audit.jsonconvention is retired. A future storage change requires an explicit system decision, versioned 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.
- INV14 — Current authority is claim-scoped.
authority: currentapproves the explicit claims inside a record's stated ownership boundary. It does not promise that every behavior of the named component, module, family, or code path has been specified. Review MUST NOT expand one narrow decision into adjacent uncontracted behavior unless the pull request's exact delta depends on that behavior. - INV15 — Review contracts toward one landing-ready intent. Authors identify one primary intent and reviewers classify each observable delta separately. A separable delta that violates current authority or requires a new human decision is removed or split before review asks the primary change to carry new authority. A specification is the path for an intentional durable decision, not the default remedy for unrelated scope discovered during review. An added or changed public API row that no current record decides is the exception: it goes to human review for an owner's decision instead (change coupling step 6).
- INV16 — Specs govern; generated review context only informs. Committed current component, module, family, design, theme, architecture, and system records own intended product behavior. Reviewer-generated summaries, sections, checklists, tests, screenshots, measurements, and recommendations are context or evidence only. They may prove conformance, contradiction, or an implementation defect; they MUST NOT invent direction, authorize a delta, reverse a human hold, or upgrade the authority result.
- INV17 — Missing review context stays problem-bound. Review reads the pull request and current authority first, then fills only missing context. It traces why the problem occurs, why it harms the affected task, and why the harm matters; maps the proposed solution and each primary or supporting delta back to that problem; and identifies independently removable tagalongs. Product impact remains owned by the applicable product record. Review may explain who is affected, in what supported state, and what the change enables or prevents, but that generated explanation remains context until a current canonical owner records the behavior.
- INV18 — Product contracts preserve implementation freedom. Component, module, family, design, theme, and system specifications own observable inputs, outputs, states, guarantees, failures, compatibility, and caller-visible ownership. A new or materially amended requirement MUST NOT prescribe internal modules, files, function names, algorithms, data structures, storage layouts, manifests, journals, locks, transaction protocols, or CI job/workflow topology unless that exact mechanism is itself an intentional public contract. Internal ownership, seams, and mechanisms belong in an architecture record. A verification map names evidence sufficient to prove a claim; it does not authorize the implementation or CI structure that produces it. Existing current records continue to govern their explicit claims until their human owner deliberately migrates them; this invariant does not silently invalidate or reinterpret those records.
- INV19 — Automated spec review informs a human decision. A pull request whose primary intent creates, amends, adopts, or supersedes a product contract receives written advisory analysis before the named human owner decides it. The analysis identifies the canonical knowledge owner, applicable current claims, overlapping current and open work, ownership collisions or missing owners, claim-scope gaps, behavior-versus-architecture leakage, and exact claims to keep, remove, move, or clarify. Automation may report contradictions, evidence gaps, and proposed edits; it MUST NOT approve, adopt, ratify, or make the contract current. A human approval remains required even when the advisory analysis finds no defect.
- INV20 — Global review routing is explicit and claim-scoped. A cross-cutting
baseline participates without a component backlink only when its
review-applicability:v1block declaresscope: "global"and maps a semantic trigger or a concern to exact claim ids in that same record. Review loads matching current global claims before narrower records, then resolves the direct component, module, or family owner first when it governs the delta. The marker never makes the whole record, adjacent claims, drafts, or proposed-head authority govern. Every routed match records the base authority commit, record digest, record id, path, trigger or concern, claim id, claim title, and deterministic match reason. A record that owns a shared concern MAY list it in the block'sconcernsmap: the shared utility's names, the code patterns that re-implement it, and the claims it routes. A change whose added shipped-source lines match a concern routes those claims whatever the component record'sreview_triggerslist, and each match names the line that matched. - INV21 — Component-local visual intent stays local and durable. The optional
### Design decisionstable under## Design relationshipsbelongs only to component- or module-local appearance intent that a future redesign must reconsider. Authors cite, reuse, or amend stableDD1,DD2, … rows before adding one. Exact pixel tuning normally remains in code and visual evidence; shared or cross-component rules remain indocs/design/. Team design owners may commit a row with the pixels and evidence in one atomic appearance-only pull request. External contributors follow the normal contribution flow and MUST NOT be asked to author specifications; maintainers own any missing authority. A human request supplies intent but becomes committed current authority only through owner approval of the current spec content (DEC-14).
Review evidence placement
- INV22 — One-off evidence stays with the change. Ad-hoc screenshots,
recordings, measurements, sensor receipts, and run logs are attached or linked
from the pull request that uses them, not committed to
mainas disposable assets underdocs/pr-assets/or another source directory. Public GitHub attachments are the preferred home for manually published one-off evidence. Standing records keep durable conclusions and verification relationships, not individual run inventories. Accepted visual baselines, reusable stories and test fixtures, shipped documentation media, and repository-owned receipts explicitly permitted by their current owner remain versioned with the code. - INV23 — Cleanup preserves historical evidence. Removing disposable assets
from the current tree MUST NOT rewrite history or break existing commit-pinned
evidence links. Before deletion, every removed file has a verified public
retained copy. A linked commit outside retained
mainhistory needs a durable retention anchor at that exact commit; a commit hash or a temporary branch alone is insufficient. An immutable non-releaseevidence/tag may retain historical Git-hosted evidence when attachment publication is unavailable. Its name stays outside release-tag conventions and automated pruning, and it MUST NOT be moved or removed while the evidence is referenced. Cleanup verifies the remote anchor, exact bytes, and existing links before removing source files. - INV24 — Storage does not change proof or authority. The pull request's text states the claim, tested build, relevant state, observed result, and evidence links; an image or expiring artifact is not the only record of the conclusion. Attachments remain evidence under INV16, not authority. Owner-specific receipt requirements, operational audit stores, and CI artifact lifetimes remain with their current owners. AST-009 owns real-AT receipts; INV12 owns the operational audit datastore. AST-029 FR5 and FR10 own the audit pull request's evidence receipt and exact-head eligibility report. AST-030 FR12 owns shared visual-regression execution and baseline adoption. This placement rule does not add a capture owner or require permanent archiving of every CI run.
Path discovery
- INV25 — Every current record is reachable from a path. Each current record is linked from at least one repository path that is not itself a knowledge record, through placement, a path field, a name, a citation, inheritance, or a deciding link. A path-first lookup reports a path with no linked record as unrouted. It never infers a link from a file name, extension, or directory name.
- INV26 — Path applicability locates a record; claims still decide. A record
whose rules apply to paths that no other link reaches declares them in one
path-applicability:v1block. A matching path lists the record. The match does not widen any claim beyond its stated scope (INV14), does not make the record outrank a narrower owner (INV9), and does not require behavior to live in the named files (INV18). Every pattern matches at least one tracked file.
Record coverage
- INV27 — Every specification in the repository is a knowledge record. A
specification, a file that states what any part of the system must do as
opposed to consumer docs, guides, and READMEs that explain how to use it, is
a record of a kind this record names, in any package that exists today or is
added later. It carries
that kind's frontmatter, follows that kind's template in
docs/templates/knowledge/, and sits at that kind's canonical location (Owning code). No package defines its own spec format, template, or location. Discovery treats every tracked Markdown file named*.spec.md, and every tracked Markdown file under a directory namedspecs, as a record candidate, and a candidate that is not a valid record failspnpm check:knowledge.README.mdindex files,plan.mdimplementation plans, and the paths discovery already ignores are not candidates.
Consumer docs
INV28 — Every public hook has a minimal, runnable example that demonstrates it. A public hook is a hook that a package's committed API report lists. Its documentation includes at least one realistic, runnable example: a live template block that names the hook as its example target (
exampleFor, oralsoExampleForwhen the block also serves another page). The example:- shows the hook inside a component solving the use case its docs state;
- imports the package's own code only through its public entry points;
- covers the hook's main parameters and return values;
- passes the docs build;
- gets its visible behavior from the hook itself, so removing the hook breaks what the example shows; and
- is minimal: only the code needed to show the use case, with no unrelated UI or styling.
How a docs page selects and orders its example blocks belongs to
architecture:template-authoring. A public hook without a conforming example is a docs gap, tracked as an issue in the repository's issue queue (DEC-16).
Source comments
- INV29 — Source comments explain only non-obvious work. Names, structure,
and control flow make source code explain itself. A comment that restates
what the code does is a defect: the fix is clearer code, not a comment. A
source comment explains only what a reader cannot see in the code: a reason,
a constraint, an invariant, or a browser or platform quirk. It never narrates
the code, restates a name or a type, names a pull request, an issue, or a
date, or quotes or cites a knowledge record. The record links the code, so
pnpm specs:for <path>finds the governing record, and a component's{Name}.spec.mdholds its record ids. When a comment's citation is a file's only link to a record or claim, a record links the file first, and only then is the comment removed, sopnpm specs:for <path>lists the same records and cited claims before and after. A whole-record citation, such asAST-108, becomes anapplies_to,verified_by, orpath-applicability:v1link in the cited record. Those links reach the whole record, so they cannot keep a cited claim, such asAST-108 FR4. A claim-scoped reference in the file's own component, module, or theme record keeps it, in the reference field for the cited record's kind, such assystem_specs: [spec:AST-108/FR4]in theSpinnerrecord forSpinner.tsx.pnpm check:knowledgeresolves only a/DEC-Nclaim in a theme or module record'sreferences, so a claim citation in a theme or module file, such asAST-079 FR2inbutterTheme.ts, stays until that check resolves any claim suffix. Until a record holds one of these links, the citation stays. Comments follow the ASD-STE100 Simplified Technical English style: at most 20 words in an instruction and 25 in a description, one topic per sentence, active voice, present tense, simple words with one meaning each, and no idioms or filler. These comments stay:- the copyright line;
- the file header:
@input,@output,@position, andSYNC:reminders, in about 12 lines at most, with no prose that repeats the main JSDoc; - JSDoc on exported components, props, hooks, and utilities, with untagged
@examplefences; - the note on each Effect that names the external system it synchronizes
(
architecture:react-component-runtimeINV3); - directives a tool reads: lint and TypeScript directives, the
@pr-a11yrouting lines in the header comments of browser accessibility spec files thatspec:AST-030FR12 reads, and any other comment line a repository tool parses.
Example. This comment breaks INV29. It cites a record, packs several topics
into long sentences, and restates the finalFocusRef line below it:
// The returned focus shows the focus-visible ring only after keyboard
// input (`architecture:interaction-modality` INV1). The native close
// may already have restored focus to the target with a ring; the helper
// clears it first.
//
// With a sheet still open beneath this one, focus returns into that
// sheet: to the opener when it is there, else to the sheet's panel.
//
// An explicit `finalFocusRef` always receives focus, as released. The
// recorded opener of a non-modal sheet does so only if the person was
// still in the sheet when it closed (`hidePopover()` never moves
// focus, and the page behind it was live, so focus the person took
// elsewhere stays there).
This comment follows INV29. Each sentence states one fact, and the code states the rest:
// The native close can show a focus ring on the target. Clear it. The ring
// shows only after keyboard input.
//
// If a sheet is open below, focus goes to this sheet's opener when it is in
// that sheet, else to that sheet's panel.
//
// A non-modal sheet returns focus to its opener only if focus was still in
// the sheet. The page behind it stays live, so the person can move focus
// away first.
External links
- INV30 — A new external link from outside the team needs a human owner. A
pull request whose author is not on the team that adds an external URL (a
link to a site other than this repository and Astryx's own sites) to the
docsite or to package documentation is never approved or merged by
automation. A human owner approves it, and the reviewer checks that each new
link belongs. Team-authored links follow the normal gates (DEC-17). In this
rule:
- the team is the accounts listed in
.github/ENGOWNERSor.github/DESIGNOWNERSonmain. Bot accounts are never on the team. - Astryx's own sites are this repository on GitHub, the Astryx docsite,
Astryx preview deployments, and the
@astryxdesignpackages on npm. Links to web standards and platform references (W3C, WHATWG, MDN, TC39) and reserved example domains are not external links for this rule. - a human owner is
cixzhangor a DESIGNOWNER, approving the exact head.
- the team is the accounts listed in
Approval lines
- INV31 — A record's approval lines are append-only. A pull request that
changes or removes an existing decision's Decider line, or replaces a
record's
approved_bywith a different account, needs that original decider's approval at its exact head;cixzhang's own pull request counts as hers. Adding a decision or an approver needs nothing extra (DEC-18). In this rule:- the original decider is the account the existing line names.
- approval is an approving review at the exact head, or a
/approve-spec <full head SHA>comment, from that account. Any decider other thancixzhangapproves the exact head, also on their own pull request. - a change is an edit to or removal of the line, a removed decision included. A line that only moves, text added after an unchanged Decider line, and a placeholder decider that a real decider replaces are not changes.
Public API scope
- INV33 — Every public API row a pull request adds or changes is named in its scope. A pull request names the components and modules it changes, and lists its public API rows by component. A row outside that named scope that no current owner-approved record decides is sent to an owner with the row listed, and the pull request doesn't merge until the row is named and owner-approved, or split into its own pull request. A row outside the scope that a current record decides needs no further step (INV25), but the status still lists it as outside the scope, so a reviewer sees it. A behavior handler (a public event or callback prop, such as
onClick, that makes a component act on input) added outside the scope warns.
Path applicability
Use this optional block when a record governs paths that its placement, path fields, names, and inherited links do not reach. A record that is already reached from every path it governs stays unmarked.
{
"paths": ["apps/docsite/**", "packages/**/*.doc.mjs"]
}
In an opted-in record, replace the example marker with path-applicability:v1.
Patterns are repository-relative and case-sensitive. ** is a whole segment
that spans any number of segments, * matches within one segment, and ?
matches one character within a segment. Patterns use only letters, digits,
_ . @ - /, and those wildcards. A bare ** is rejected. The checked-in
validator rejects malformed blocks, unsafe or repeated patterns, and patterns
that match no tracked file.
Global review applicability
Use this optional block only when named claims apply across otherwise unrelated component owners. Ordinary component, module, family, design, architecture, theme, and system records remain unmarked.
{
"scope": "global",
"triggers": {
"public-api": ["FR1", "DEC-2"],
"accessibility": ["AR1"]
}
}
In an opted-in record, replace the example marker with
review-applicability:v1. Trigger names use this closed vocabulary:
accessibility, behavior, compatibility, component-slots, docsite,
interaction, layering, layout, motion, navigation, platform,
public-api, react-runtime, responsive, scrolling, specification,
styling, testing, theming, tokens, and visual. Every trigger has a
non-empty list of unique claim ids, and each id resolves to an explicit numbered
claim in that record. A block may add, or carry instead of triggers, a
concerns map (INV20). Each lower-kebab concern lists claims and at least one
of names (identifiers of the shared utility) and patterns (regular
expressions for code that re-implements it):
{
"scope": "global",
"concerns": {
"slot-presence": {
"names": ["isRenderable"],
"patterns": ["typeof [\\w.]+ !== 'boolean'"],
"claims": ["INV16"]
}
}
}
A concern lives in the record that owns its claims, so a claim is routed from
one source. The checked-in validator rejects unsupported triggers, malformed
blocks, missing or duplicate claims, invalid patterns, and empty routing.
scripts/review-global-baselines.mjs requires both the exact reviewed head and
its full base authority commit, verifies that commit is the head's origin/main
merge base, emits deterministically sorted match rows, and lists in
concernMatches the claims whose concerns the head's added lines match. It therefore cannot
read a proposed head as its own authority. Consumers load those rows before narrow lookup, preserve their
provenance in a review receipt, and apply only the cited claim after the direct
owner has been resolved.
Writing specifications and contracts
These rules preserve semantic fidelity while putting the decisions a reader needs first. They are authoring guidance, not a quantified claim about human readability. They apply prospectively to new or materially revised architecture, component, and module specifications; they do not require historical rewrites.
Before writing:
- Search current records for the behavior, public symbols, affected paths, and proposed canonical owner/id.
- Search open pull requests for the same owner path, symbols, and semantic terms.
- 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.
Begin each component or module contract with this reader-first projection after its title:
| Area | Contract |
|---|---|
| Public contract | State the exact public API, concept, or syntax delta; write None when none changes. |
| Behavior | State the observable governing behavior, including the decisive default, boundary, or precedence rule. |
| End-user impact | Name who is affected, in what state, and what improves, worsens, or remains unchanged. |
| Builder impact | Name migration work and every new caller choice; write None when there is no new burden. |
| Compatibility/readiness | State default compatibility, additive/breaking status, authority and implementation state, and material evidence still pending. |
| Review checks | List the few concrete conditions that make an implementation or proposal rejectable under this contract. |
| Governing rules | Link the canonical owner and only the current clauses needed to justify the projection. |
Architecture records use the same position and footer with architecture-specific rows:
| Area | Contract |
|---|---|
| Governing contract | Name the observable current decisions this architecture serves; write None when no product contract changes. |
| System behavior | State shipped system behavior, including the decisive invariant, boundary, or precedence rule. |
| End-user impact | Name who is affected, in what state, and what improves, worsens, or remains unchanged. |
| Builder impact | Name the implementation decisions, coordination work, or workarounds this architecture removes or adds. |
| Compatibility/readiness | State compatibility effect, authority and implementation state, and material evidence still pending. |
| Review checks | List boundary violations, product-API mechanism leaks, or lost invariants/evidence distinctions that make a change rejectable. |
| Governing rules | Link the deciding specs and only the current clauses needed to justify the projection. |
The table is a review projection; the body remains authoritative. The projection
itself does not make a record shorter. Size falls only when authors remove true
duplication from the body without dropping contract semantics. Review checks
project settled requirements and boundaries from the body; they do not invent
policy or reopen a decision. When citing a list-item clause such as an AST-002 FR,
use its exact visible label and canonical file link. Do not invent a fragment URL
for a clause that has no stable heading or explicit anchor.
Then write the authoritative body:
- Describe the system in the present tense, not the project that produced it.
docs/contributing/spec-writing.mdturns this rule and INV10 into a rubric; a pull request that creates or changes a record reports that rubric's results in its description before review. - Use familiar words and short, direct sentences.
- State each rule fully once, beside the conditions and exceptions that control it. Later sections cite its ID or canonical owner instead of restating the prose.
- Contract only the semantic slice being decided. Name adjacent behavior as a
non-goal or uncontracted gap; do not fill it merely to make the record
current. - Do not duplicate consumer prop tables, usage recipes, shared-system mechanics, current audit dumps, or implementation steps. Link their canonical owners.
- Use readable tables for branches or state matrices when they improve scanning. Never remove contract content merely to shorten a record.
For routine local appearance intent, a component or module record may include the
optional versioned Design decisions table under Design relationships. Each row
uses a stable, unique DD id and states the decision, its intent or reason, where
it applies, and allowed variation. Add a row only when the intent is durable enough
that a future redesign must reconsider it. Reuse or amend an existing row first.
Do not copy exact pixel tuning out of code/evidence or shared rules out of
docs/design/. A header-only table is valid in a template; an authored block has
at least one complete row.
Plain language must preserve normative force, predicates, cardinality, defaults, compatibility, authority, owners, IDs, evidence state, and decision status. Do not delete, weaken, merge, or hide distinct normative content. Replace a local fact with a link only when this record's ownership rules assign that fact to another canonical owner.
Qualifiers and authority verbs are contract semantics, not polish. Words such as
only, every, consistently, current, records, owns, delegates, and
inherits MUST NOT be dropped, generalized, weakened, or upgraded during a
rewrite. When reshaping a rule, keep its action, activating conditions,
exceptions or non-goals, owner, and evidence state in the same row or bullet as
the claim they limit.
Do not optimize for a line, word, byte, or percentage-reduction target. First remove true duplication, shorten prose without changing meaning, use readable tables or lists, and link genuinely shared authority as INV2 requires. Keep every load-bearing condition, qualifier, boundary, decision, and evidence distinction that remains. Human scanability and semantic fidelity win over size.
Same rule, plainer form
Dense:
When
itemscontains exactly one visible item, the component MUST announce that item exactly once; whenitemscontains zero or more than one visible item, it MUST NOT announce an item, and consumers that omititemsMUST retain the existing silent behavior.
Plain:
| Condition | Required behavior |
|---|---|
items is omitted |
MUST keep the existing silent behavior. |
| Exactly one visible item is present | MUST announce that item exactly once. |
| Zero or more than one is present | MUST NOT announce an item. |
The plain version changes the shape, not the meaning.
Before review
- Compare the edited text with its source and confirm that every contract property named above remains explicit.
- Confirm each rule's action, conditions, qualifiers, exceptions or non-goals, owner, authority verb, and evidence state remain explicit and adjacent to the claim they limit.
- Confirm the projection states the public delta, behavior, end-user and builder impact, compatibility/readiness, rejection checks, and governing rules without replacing or contradicting the authoritative body.
- Confirm tables and lists improve scanning without hiding content, and no content was removed merely to meet a size target.
When current records disagree
- A draft is context only and cannot conflict with current policy.
- Identify the canonical owner from the fact's scope: aggregate component behavior, independent public module behavior, family behavior, design representation, one theme's semantics/mappings, cross-theme architecture, consumer usage, or audit evidence.
- If two current records make different claims, review stops. Do not choose by
recency, path proximity, or specificity; record a
novel-humangap. - Resolve the gap by changing the canonical owner and removing the copied claim. A deliberate exception is recorded by that owner; affected records link to it instead of restating it.
- A system-spec decision may authorize the change, but the current owning contract must change in the same pull request before reviewers rely on it.
Change coupling
A document does not stay current by convention alone.
Before any component, module, family, design, theme, or architecture record becomes
current, the repository must support this flow:
- The record names the code surface that can affect it and the checks that verify it.
- A pull request touching that surface triggers a focused contract review.
- Review starts from the pull request's declared primary intent and classifies
each public delta independently as one of five results:
preserves: the exact delta restores or retains current authority without adding public API or behavior beyond it;settled: an existing current human decision covers the exact delta and is cited;violates: the exact delta contradicts current authority;novel-human: no current authority settles the exact public API, behavior, ownership, compatibility, or design delta; orout-of-scope: another component, module, family, system, or product owns it.
preservesandsettledenter normal correctness review. They are eligible for approval only when the implementation and evidence also pass.violatesreceives request-changes with the smallest conforming remedy: change or remove the violating delta. Review does not recommend a specification merely to rescue contradictory implementation; an owner may separately choose to propose a policy change.- A separable
novel-humantagalong is removed or split from the primary intent. Review may request that contraction without deciding the tagalong's semantics, then continue reviewing the remaining change. Anovel-humandelta enters a private human hold only when it is the primary intent, is inseparable from it, or the author or owner explicitly chooses to pursue it. An added or changed row of a pull request's public API changes (architecture:public-component-apiINV24) that isnovel-humaninstead sends the pull request to human review with that row listed, whether or not it is separable; an owner of that record accepts, splits, or removes it, and review never requests changes for that row alone. - A bug fix is
preservesonly when it restores existing current authority without changing public API or public behavior beyond that contract. Any separable API, visual, layout, or interaction tagalong follows step 5 or 6 rather than making the restoration wait for a broader specification. - A visual correction may be
preservesorsettledwhen current component, family, design, theme, or objective accessibility authority covers its exact outcome. Real rendered evidence must prove the affected state and representative unchanged states. A new visual representation remainsnovel-human; calling it an improvement does not settle it. - Audit freshness is computed from the same code and test relationship, so a relevant code change cannot leave an audit looking current.
Audit-storage migration is a separate contract change. It requires a versioned data contract, automated conversion and reconciliation of existing wiki rows, a named source of truth during transition, sandbox-reader cutover, and rollback evidence. Repository-local per-component files are not a migration plan by themselves.
Contract before escalation
Review and build should converge on the smallest ideal change that can land:
- State the pull request's primary intent and partition its observable deltas.
- Apply current authority to each delta. Existing design and objective standards can settle a visual correction even when a component record does not enumerate its exact paint.
- For a contradiction, conform or remove it. Do not propose changing the specification unless changing policy is itself an intentional, separately reviewable goal.
- For an unsettled but separable delta, remove or split it. Continue the primary change without asking the contributor to solve adjacent system design. An undeclared public API row is the exception: it goes to human review for an owner to accept, split, or remove (change coupling step 6).
- Escalate only a surviving, intentional
novel-humandelta or an undeclared public API row. Record only the exact decision needed for that delta; adjacent module behavior may stay uncontracted.
The actionable review result names the acceptance criteria for that landing-ready contraction. It does not merely report that authority is missing.
Recording a new human decision
- A contributor explains the intended behavior and primary intent in normal pull-request language and responds to review. External contributors keep the normal contribution flow: they are never asked to author or update a specification.
- A reviewer or agent applies the contraction path above. Only a surviving,
intentional
novel-humanquestion proceeds; the contributor does not invent the answer or specify unrelated adjacent behavior. An undeclared public API row also proceeds, as change coupling step 6 describes, rather than being removed or split by review. - An authorized owner answers in the pull-request review.
- A maintainer or agent records that ruling in the canonical owning record.
- Prefer a commit in the same pull request when maintainers can update the branch.
- If they cannot update the contributor branch, open a small linked spec pull request below it and rebase the implementation after that decision lands.
- If the direction is accepted, the contributor updates the code when needed.
- If the direction is rejected, the rejected implementation is removed or changed. Record the rejected alternative only when the boundary is consequential and likely to come up again.
- The final commits invalidate prior approval. The owner approves the exact heads after the record and implementation agree.
If no implementation direction is accepted, close the contributor pull request. The maintainer-owned spec pull request remains only when the ruling is useful independently.
Review comments are evidence of the conversation; the checked-in record is the canonical decision.
Record the durable outcome, not the review transcript. A ruling belongs in a canonical record when at least one is true:
- it changes or clarifies an owning component, module, family, or system boundary;
- it establishes a requirement or prohibition future work must preserve; or
- it rejects an alternative that is consequential and likely to recur.
A prop name, implementation mechanism, or failed visual experiment from an abandoned pull request stays in review history unless that detail itself passes this test.
Use a separate lower spec pull request only when the ruling changes a shared contract beyond the contributor change and should land or be reused independently. The implementation pull request then rebases onto that decision.
Examples:
- NumberInput changes its stepping math. Its current contract says the final
operation clamps to
min/max, and the mapped tests still pass. Result:preserves; continue to normal correctness review with no human question. - A new NumberInput path uses the same previously approved transformation order.
Result:
settled; cite thatDECand continue to normal correctness review. - A package-exported context changes a required function parameter while its
current contract preserves the earlier operation shape. Result:
violates; request the smallest conforming change. A new compatibility policy is a separate proposal, not the default repair. - A scroll-overflow fix also introduces a new hover disclosure. The overflow restoration proceeds under its current layout authority. If disclosure lacks authority, remove or split that separable visual tagalong; do not require the bug fix to specify the whole interaction module.
- Selector removes empty indicator space as its primary intent, but no current
decision says whether option labels must stay aligned. Result:
novel-human; hold privately while the owner decides the exact alignment contract. - A product requests a one-off width prop for a family-owned input layout rule.
Result:
out-of-scope; route the change to the family contract rather than creating a component-specific API.
A draft record cannot clear a review gap. Only a verified current contract or
an applicable decision can produce preserves or settled.
The bootstrap does not mark any component, module, or family record current until this flow passes the historical review benchmark and is enforced on pull requests.
Owning code
AGENTS.mdpoints reviewers to the narrowest relevant record.docs/templates/knowledge/contains the only authoring forms; a package keeps no template of its own (INV27).- Component records live in
docs/specs/components/<ComponentRoot>/, one folder per component root, as direct<PublicName>.spec.mdchildren (DEC-15). The folder tree mirrors the component's source tree: a component root is a component directory of Core (packages/core/src/) or Lab (packages/lab/src/), or a top-level module of a flat component packagescripts/component-packages.cjsregisters (Charts, RichText, and Vega), whose record isdocs/specs/components/<PublicName>/<PublicName>.spec.md. The package that owns a record is the one whose source tree has its component root; when two packages have a root of that name, it is the one holding the record's code. A platform implementation's record sits in the same folder as<PublicName>.<language>.spec.md(for exampledocs/specs/components/Button/Button.swift.spec.md), has the idcomponent:<language>/<PublicName>(for examplecomponent:swift/Button), names its core component inplatform_of(component:<PublicName>), and states only what that platform adds or must do differently; the core record keeps the shared contract (INV2). Until the core component has its own record, its public source and documentation stand in as that contract. The public name normally matches the root; a parent/member exception requires an exact top-level or full inline consumer-doc entry in that root. Public semantic module records are nested at least one directory beneath the same folder as<PublicName>.spec.md, usually inmodules/, or in a plugin's own folder such asTable/plugins/rowStatus/. The subdirectory need not match where the module's code sits: lookup reaches the record by the code's file name or itsverified_byevidence. The parent component'smoduleslist and the module'sparent_componentfield must agree. Neither a component package's source tree norpackages/native/apple/Sources/holds a*.spec.md. Hidden, fixture, test, generated, build-output, coverage, dependency, and*.generated.spec.mdpaths are ignored consistently by discovery and PR routing. - Wiki
component-scores.jsonis the current operational audit datastore. The historical<PublicName>.audit.jsonreservation never received a schema or active records and is retired by INV12. - A record governing one package's cross-component rules lives under that
package's
specs/directory as<slug>.spec.md, with kindarchitectureand an id ofarchitecture:followed by the package name, each directory betweenspecs/and the file, and the slug, joined by hyphens. For example,packages/native/specs/swift/accessibility.spec.mdisarchitecture:native-swift-accessibility. Repository-wide architecture stays indocs/architecture/. packages/themes/<theme>/<theme>.spec.mdcontains that package theme's canonical record;docs/themes/README.mdis guidance and an index only.docs/schemas/knowledge/defines required structure.scripts/check-knowledge.mjsvalidates templates, records, approval metadata, optional component/module design-decision tables,path-applicability:v1blocks, and INV25 reachability.scripts/specs-for-file.mjs(pnpm specs:for) resolves the records linked to a path.--unroutedlists tracked paths with no linked current record;--unreachedlists current records no path reaches..github/scripts/component-design-decisions.cjsclassifies current component/module changes as no DD change, DD-only, or mixed from trusted base and head bytes. DD-only requires unchanged path, kind, authority, and every byte outside a valid optional block..github/scripts/knowledge-paths.cjsholds the one list of record paths. It names the recordscheck:knowledgediscovers and the owner-gated paths: every record; every Markdown file underdocs/specs/or a package'sspecs/ordocs/architecture/, READMEs included; every Markdown file in the family, design, architecture and theme-docs folders except each folder'sREADME.mdindex; every*.spec.mdin a theme package; and the normative design assets. Ignored locations stay ignored..github/scripts/change-scope.cjsidentifies pure spec-record changes and the owner-gated paths a change touches, and classifies paths for callers outside the workflow (--classify-paths)..github/workflows/review-signal.ymlpublishes the one review gate,review-required, which carries spec-owner approval too (DEC-14). One owner approval covers every knowledge-record change in the pull request and binds the approved spec content, not a commit. Approval for every record kind derives from.github/ENGOWNERS; current design and theme records, normative design assets, and DD-only current component/module changes 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 other component/module edit requires both groups. An owner-gated Markdown file with no authority of its own, such as a generated table beside a spec, requires an engineering owner. Record metadata never self-authorizes. The gate decides approval only; it never enables auto-merge. The gate does not detect a new external link from outside the team (INV30); see the enforcement gap under Verification..github/workflows/review-signal.ymllets a DESIGNOWNER author bypass the engineering gate only when trusted-base code verifies every changed Core line against the fetched base/head source bytes as a conservative declaration inside a realstylex.createcall, and no other code reason applies. The classifier also rejects direct interaction, operability, and scroll-control declarations—including hit testing, touch behavior, selection, resize, cursor, visibility, overflow, snapping, and scrollbar affordance—on either diff side. Contributors and mixed or behavioral changes remain gated. Safe-space classification considers both current and previous paths: only changes whose every path is safe are excluded, and any rename crossing that boundary is an engineering reason. Engineering and design reviews count only when theircommit_idequals the current pull-request head. The direct reconciler clears only a current-head gate already owned byreview-signal; an effective ENGOWNERCHANGES_REQUESTEDorDISMISSEDstate first restores the hard status gate to pending, then restores its advisory label. A failed status write performs no preceding label mutation. Approval, withdrawal, and dismissal all recheck the head immediately before mutation, and an ungated head never acquires a gate from review state alone. For an author whose live repository permission is write or admin, the review app named in theREVIEW_APPrepository variable also satisfies the engineering gate under DEC-11. Only that app's latestAPPROVED,CHANGES_REQUESTED, orDISMISSEDreview whosecommit_idequals the current head counts. Both workflows read the author's permission at every evaluation and publish the status with their own Actions token.
Deciding specs
DEC-1 — Current-record conflicts do not resolve by precedence
Reference: architecture:knowledge-contracts/DEC-1
Decider: cixzhang, 2026-08-30
A current record does not override another by being newer, narrower, or closer to the code. Review stops, identifies the canonical owner, and resolves the conflict there. Other records link to the owning decision rather than copying it.
Rejected: silently choosing the newest or most specific record, because that turns documentation order into unreviewed system policy.
DEC-2 — New rulings normally stay in the contributor pull request
Reference: architecture:knowledge-contracts/DEC-2
Decider: cixzhang, 2026-08-30
A human ruling is normally discussed in the pull request that exposed the gap. The contributor is responsible for explaining intent and changing their code; maintainers and review agents are responsible for the spec system. They record the ruling in the same branch when possible, or in a small linked lower spec PR when the contributor branch cannot be updated. Rejected implementation is removed or changed; a rejected alternative is recorded only when it protects a consequential boundary from being debated again. Final owner approval of the current spec content attests that the decision and implementation agree.
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.
DEC-4 — Contraction precedes new authority
Reference: architecture:knowledge-contracts/DEC-4
Decider: cixzhang, 2026-09-11
When an otherwise reviewable change carries a separable contradiction or unsettled decision, remove or split that delta and keep the primary intent moving. Recommend a specification only when the surviving delta is intentionally pursued as durable behavior, not because review discovered adjacent incompleteness. An undeclared public API row is the exception: change coupling step 6 sends it to human review for an owner's decision, and review does not remove or split it.
Rejected: turning every uncontracted tagalong into a specification project, because that makes a narrow repair absorb unrelated design work and leaves the contributor without a landing-ready path.
DEC-5 — Current approval is claim-scoped
Reference: architecture:knowledge-contracts/DEC-5
Decider: cixzhang, 2026-09-11
A current record authorizes only its explicit claims within its stated ownership
boundary. It may deliberately leave adjacent behavior uncontracted. Reviewers do
not treat current as certification that a whole component or public module is
fully specified, and do not demand unrelated coverage before applying a narrow
approved decision.
Rejected: requiring a narrow visual or behavior decision to contract every API, composition, accessibility, and implementation fact of the named module.
DEC-6 — Product specs govern; generated review context informs
Reference: architecture:knowledge-contracts/DEC-6
Decider: cixzhang, 2026-09-12
Committed current product records decide intended behavior. A review begins with those claims and uses generated context, checklists, tests, screenshots, measurements, and recommendations only to prove conformance, contradiction, or a concrete defect. Generated completeness and green checks never create authority or upgrade the authority result.
When the pull request or current record leaves context implicit, review may fill the gap by tracing the problem through three why questions, mapping the solution back to that problem, and naming tagalongs. It may also explain affected users, supported states, enabled or prevented behavior, and caller burden. Those explanations remain context unless the canonical product owner records them as current behavior.
Rejected: treating a complete review form, persuasive impact story, or passing validation matrix as an alternative source of product direction.
DEC-7 — Product specs contract behavior, not internal architecture
Reference: architecture:knowledge-contracts/DEC-7
Decider: cixzhang, 2026-09-12
A new or materially amended product specification states the observable contract a conforming implementation must satisfy and leaves equivalent internal implementations free. It names an exact mechanism only when callers or interoperating systems intentionally depend on that mechanism as public behavior. Otherwise, internal ownership and seams belong in an architecture record, and verification remains evidence rather than a prescribed CI or test topology.
This authoring rule is prospective. Existing current records retain their explicit authority until the named human owner migrates them; adding this rule cannot silently void a requirement such as a legacy implementation constraint. When an amendment touches such a requirement, the owner either demonstrates that the mechanism is publicly observable or moves it to the applicable architecture record.
Rejected: promoting a successful prototype's module graph, algorithm, manifest, journal, lock, transaction design, filesystem layout, or CI job into product requirements merely because that implementation supplied the decision evidence.
DEC-8 — Spec review is advisory analysis for the human owner
Reference: architecture:knowledge-contracts/DEC-8
Decider: cixzhang, 2026-09-12
Automated review of a specification does not stop at routing the change to a human. It first produces written, evidence-backed feedback about the canonical owner, existing and overlapping claims, ownership collisions, claim scope, misplaced architecture, and exact contract edits. That analysis helps the human owner inspect the decision; it never substitutes for the owner's approval or becomes authority.
Rejected: automatically approving a specification because its checks are green, or returning only “needs human” without giving the owner the contract and ownership analysis already available to the reviewer.
DEC-9 — Global applicability routes exact claims, not whole records
Reference: architecture:knowledge-contracts/DEC-9
Decider: cixzhang, 2026-09-19
A cross-cutting rule is discoverable without a component backlink only through a
validated review-applicability:v1 block. Each semantic trigger names exact local
claim ids. Reviewers load matching current claims from the base authority commit
before narrower records, preserve match provenance, and then resolve the direct
owner first when it governs the delta.
Rejected: treating a global marker as authority for every statement in a file,
because that would erase claim boundaries and let unrelated or draft material
silently govern a change.
DEC-10 — Routine visual intent lives with its component or module
Reference: architecture:knowledge-contracts/DEC-10
Decider: cixzhang, 2026-09-23
A small structured Design decisions table in the owning component or module
spec records only durable local visual intent. One row may cover a coherent local
direction; tiny visual tuning does not create one decision record per tweak.
Existing rows are cited, reused, or amended before new rows are added. Exact
pixels remain in code and evidence, while shared and cross-component direction
remains in docs/design/.
A team DESIGNOWNER may include the local decision, implementation, and evidence
in one atomic appearance-only pull request. DD-only current-record changes route
to design approval; mixing a DD edit with another component/module contract edit
requires both design and engineering. A DESIGNOWNER approves with
/approve-spec <sha> like every other owner. The Core code gate is bypassed only when trusted-base
classification proves an existing-file declaration-only appearance diff and no
other code reason applies. Any uncertainty, contributor-authored change, behavior,
JSX, API, package, barrel, new component, or unknown runtime path fails closed to
engineering review.
External contributors explain intent and supply normal evidence; maintainers own specification work and never require contributors to author it. A request or conversation is decision input, not committed authority. The edited current record becomes reusable only after owner approval of its content (DEC-14).
Rejected: sidecar records or one design record per pixel tweak, because they split routine intent from its owner; treating a design request as authority before owner approval, because reviewable intent is not yet committed policy.
DEC-11 — A review-app approval clears the code gate for write-access authors
Reference: architecture:knowledge-contracts/DEC-11
Decider: cixzhang, 2026-10-15
An author with write or admin permission on the repository is an internal contributor, whether or not they are an engineering or design owner; designers and partners with write access are included. For those authors, the latest exact-head verdict of the configured review app decides the engineering gate: an approval clears it, and a later request for changes, a dismissal, or a new commit makes it pending again. An effective ENGOWNER request for changes on the exact head keeps the gate pending over an app approval, and an ENGOWNER approval still clears the gate for every author.
Authors without write permission, including read-only members and fork
contributors, keep ENGOWNER approval as the only way to clear the gate. The
permission comes from the repository's collaborator permission at evaluation
time, not from owner lists, organization membership, or author association. An
unset REVIEW_APP, an unreadable permission, or any lower permission leaves the
app's reviews without effect. The status is published by the workflow's own
identity, never by a person's account.
Rejected: counting any app approval on the pull request, because an approval of an earlier head or one followed by a request for changes would keep the gate clear.
DEC-12 — Records declare the paths they govern in an optional overlay
Reference: architecture:knowledge-contracts/DEC-12
Decider: cixzhang, 2026-10-21
A record that governs paths no other link reaches declares glob patterns in an
optional path-applicability:v1 block, beside review-applicability:v1. The
overlay is independently versioned, so opting in does not change a record
kind's required shape or migrate other records. A path-first lookup lists a
matched record; claim scope, precedence, and implementation freedom are
unchanged.
Rejected: a required applies_to field on every kind, because it would migrate
every active record to declare paths most already reach through placement or
inheritance. Rejected: regular expressions, because a reviewer cannot read
their reach at a glance and they over-match silently.
DEC-13 — Every spec is a knowledge record, wherever it lives
Reference: architecture:knowledge-contracts/DEC-13
Decider: cixzhang, 2026-10-23
Specification records in any package, including packages added later, use the
record kinds, frontmatter, templates, and placement this record defines, and
discovery fails a spec-shaped file that is not a valid record. A platform
implementation's component record is a component record with a
language-qualified id that names its core component, so the core record keeps
the shared contract and the platform record holds only the platform's part.
Until the core component has its own record, its public source and
documentation stand in as that contract.
Rejected: package-local spec formats, because their records skip structure checks, the owner gate, and path routing.
DEC-14 — One owner approval binds a pull request's spec content
Reference: architecture:knowledge-contracts/DEC-14
Decider: cixzhang, 2026-10-28
A spec owner reviews a pull request's knowledge-record changes together and
approves or reworks them as a whole. The approval binds the spec content:
one fingerprint over every changed owner-gated path, each read at a commit. In
Markdown records the fingerprint omits the front-matter authority,
approved_by, and approved_at values, so recording an approval and moving a
record from draft to current never change it. The workflow computes every
fingerprint from the pull request's files; no comment, label, or status
supplies it.
Approving acts. Each of these, by an eligible owner, approves the content of the commit it names, and counts while that commit's fingerprint equals the current head's:
- an
/approve-spec <sha>comment naming a full commit SHA; the SHA states which content the owner reviewed; - a GitHub approving review, for its commit.
/revoke-spec, with or without a SHA, and a request for changes on other spec content withdraw that owner's approval until they approve again. A request for changes on the current spec content holds the gate until that owner approves again. Reactions are not approvals. Eligibility follows the owner groups above. An ENGOWNER author may approve their own pull request with/approve-spec; an approving review by the author never counts. Design owners listed in.github/DESIGNOWNERSapprove 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-specon their pull request and their approving review on a contributor's pull request..github/scripts/spec-owner-decision.cjspicks the owner group by record kind only and has no check for an accessibility requirement or a deprecation.- an
What keeps approval. Commits that change only other paths, merges from the base branch, rebases, and approval bookkeeping keep the fingerprint, so they keep every approval.
What resets it. A change to approved spec text, a newly changed spec path, or a head that drops an approved spec change; the earlier approval stops counting until an owner approves a commit that carries the current content.
One review gate.
review-requiredcarries both the code review and the spec approval. Code review leads while it is missing; once it is satisfied, a missing spec approval shows on the same status; success needs both. A missing approval ispending, never a failure. The status names who can approve:Spec groups still missing review-requiredtextengineering (alone or with design/theme) ⏳ Waiting for human spec approval: an eng owner can reply /approve-spec <sha>design or theme only ⏳ Waiting for human spec approval: a design or eng owner can reply /approve-spec <sha>A request for changes holding the gate names its owner instead: `…: @owner
requested changes and can reply /approve-spec . An approved spec change reads ✅ Spec approved by @owner` beside the code review result. An ENGOWNER
approval satisfies every group.
- Details. The gate's details give the head's command to copy, list the changed records (id, title, authority change, and the group each needs), the 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.
- Decision record.
spec-owner-approvalreports the spec half with a minimal description, and the other writers ofreview-requiredread the spec half from it. It is not a required check and decides nothingreview-requireddoes 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
state for the head it read. A fork review carries a read-only token and is
skipped, so owners approve a fork pull request with the command. Comments that
are not owner commands start no runner. A run that would exceed the
spec-owner job's request budget leaves the gate pending as too large to
reconcile automatically, and a maintainer-dispatched run decides it
(
spec:AST-030FR15).
Rejected: exact-head binding (recording the approval and every base merge
forced re-approval of unchanged text); per-record or per-section approval
(spec review is all or nothing); a command without a SHA (a push just before
it would be approved unseen); a separate spec status (one gate, one message);
reaction approvals (no event, so a polling job); a workflow-pushed
draft-to-current change (it starts no checks and cannot write a fork).
DEC-15 — A component's records live in one folder under docs, for every platform
Reference: architecture:knowledge-contracts/DEC-15
Decider: cixzhang, 2026-10-28
Every component record and module record lives in
docs/specs/components/<ComponentRoot>/, structured as the component's source
tree, so a person working on a component on any platform finds its core
contract and each platform's record side by side in one folder. Lookup stays
path-first: discovery reads that tree, and placement maps each record to the
source directory its folder mirrors. Record ids and contents do not change with
the move.
Rejected: records beside each package's code, because a component's core and platform records then sit in different packages and every platform package needs its own spec location.
DEC-16 — Hook examples are governed by spec, and gaps are issues
Reference: architecture:knowledge-contracts/DEC-16
Decider: cixzhang, 2026-11-01
Hook documentation is governed by this record, and every public hook's docs carry a minimal, runnable example that demonstrates the hook (INV28). A missing or non-conforming example is an issue in the repository's issue queue, sized as a contributor's first pick-up. The owner's direction: "should be governed by spec and any gaps should be issues in astryx issue queue. They would be good first pick ups by contributors" and "for any example, make sure it actually demonstrates the hook. Ideally it should appear fairly minimal".
The example-coverage report checks hook examples the way it checks component-doc examples: it reports missing and non-conforming examples and never gates a merge or release (owner decision, 2026-09-30).
Rejected: an example that renders a component which calls the hook internally, because the reader never sees the hook wired.
DEC-17 — An outside contributor's new external link needs a human owner
Reference: architecture:knowledge-contracts/DEC-17
Decider: cixzhang, 2026-11-08
A pull request from an author outside the team that adds an external URL to the docsite or to package documentation is approved by a human owner, never by automation (INV30). Automated approval must not publish links an outside contributor added without a person checking them. Team-authored links follow the normal gates.
DEC-18 — A record's approval lines are append-only
Reference: architecture:knowledge-contracts/DEC-18
Decider: cixzhang, 2026-11-08
An existing decision's Decider line and a record's approved_by change only
with the original decider's approval at the exact head (INV31). An approval line
records who decided, so a rewrite without that person names someone who did not
make the decision. Only cixzhang's own pull request counts as approval of her
own lines; every other decider approves the exact head. New decisions and added
approvers follow the normal gates.
DEC-19 — A Lab-only pull request needs no owner decision
Reference: architecture:knowledge-contracts/DEC-19
Decider: cixzhang, 2026-11-04
The owner said: "Anything lab only gets an ok". A Lab-only pull request, as spec:AST-030 FR26 defines it, needs no owner decision (INV4) for its Lab behavior or Lab API. A Lab record it changes still takes an engineering owner's /approve-spec at the pull request's head (DEC-14). A pull request that is not Lab-only under FR26 follows the normal owner rules for every part it changes; splitting out the non-Lab part makes the rest Lab-only.
Rejected: treating a pull request that also changes Core or another package as Lab-only.
DEC-21 — A public API row outside a pull request's scope needs a decision
Reference: architecture:knowledge-contracts/DEC-21
Decider: cixzhang, 2026-11-09
The owner said: "I think for big prs like 3280 we need better guard rails around preventing tagalongs". A single large import once carried Item's row onClick and container click with no decision recorded. The rule above makes such a tag-along visible before merge. Rejected: relying on review to catch tag-alongs in large pull requests.
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-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 |
|---|---|---|
| INV22–INV24 | Contributor/reviewer evidence inventory; public-link and byte verification; retained remote refs; unchanged fixture/baseline/media paths | Disposable captures enter the source tree, cleanup loses a referenced image, a temporary branch is called durable, or storage changes overwrite an owner's proof or retention contract |
| INV25, INV26, DEC-12 | scripts/specs-for-file.test.mjs, scripts/check-knowledge.test.mjs, and pnpm check:knowledge |
A current record is reached by no tracked non-record path, a lookup infers a link from a name, a pattern matches nothing or the whole repository, or a pattern match widens a claim or outranks a narrower owner |
| INV27, DEC-13 | scripts/check-knowledge.test.mjs, .github/scripts/change-scope.test.mjs, and pnpm check:knowledge |
A *.spec.md file or a Markdown file under a specs directory without valid record frontmatter, outside its kind's location, or following a package-local template passes |
| INV28, DEC-16 | apps/docsite/src/lib/exampleCoverage.mjs and apps/docsite/src/__tests__/example-coverage.test.ts (advisory: the report prints and never gates), plus review of each hook example against INV28's criteria |
The report omits a public hook that has no hook doc or no conforming example block, or a missing or non-conforming hook example fails a merge or release |
| INV29 | Baselined lint over comments in package source (not built): record ids, pull request and issue numbers, date stamps, and long quote blocks fail in new comments, and existing sites are baselined. Review reports narration and file headers past about 12 lines as non-blocking findings. Cleanup lands in per-area pull requests with no behavior change, each with a pnpm specs:for comparison of every touched file before and after |
A new comment cites a record, pull request, issue, or date, quotes a record, or narrates the code; a header grows past about 12 lines, with no lint failure or review finding; removing a comment drops a record or cited claim from a file's pnpm specs:for result because that comment was the file's only link to it; or cleanup removes or rewrites a directive a tool reads, such as a @pr-a11y line |
| INV30, DEC-17 | Human-owner review of each new external URL in a pull request from an author outside the team, enforced by review and merge tooling outside the repository; no repository CI check (the INV30 enforcement gap below) | An outside pull request that adds an external URL under package docs or the docsite is approved or merged without a human owner's exact-head approval, or a team pull request that adds one is held for a human owner |
| INV31, DEC-18 | scripts/check-knowledge.test.mjs "approval line history"; pnpm check:knowledge --base <base> lists each changed approval line with its original decider; review and merge tooling outside the repository require that decider's exact-head approval (the INV31 enforcement gap below) |
A pull request that changes or removes an existing Decider or approved_by line is approved or merged without the original decider's exact-head approval, or a pull request that only adds a decision or an approver is held |
| INV33, DEC-21 | .github/scripts/api-tagalong.test.mjs |
An added or changed row whose component is outside the title scope and the Components: line, not named in a code span or the Components: line under ## Scope, and not decided by a current record, is not listed as a tag-along; an in-scope, named, removed, or decided row is listed as a tag-along; a decided row outside the scope is missing from the summary; a row matches another package's components; or an unreadable API changes file exits 0 |
| DEC-15 | .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs, and pnpm check:knowledge |
A component or module record outside docs/specs/components/<ComponentRoot>/, a *.spec.md left in a component package's source tree or beside a Swift view, a record matched to the wrong package when two share a root, a record whose component root no registered package's source tree has, a platform record whose id or platform_of does not match its path, or a platform record change that skips the spec-owner gate |
Evidence placement is enforced by contributors and reviewers. The local
docs/pr-assets/ ignore prevents accidental staging; it is not a blocking CI
check and does not prevent force-added evidence elsewhere.
Discovery reads each package's architecture records
(packages/<package>/specs/…/<slug>.spec.md): pnpm check:knowledge checks
them as it checks any architecture record, plus their kind and the id their
path gives, and the spec-owner gate treats them like records in
docs/architecture/.
Current enforcement gap: discovery does not yet read other record candidates
outside docs/, themes, and package specs/ records, such as Markdown under a
specs directory that is not a <slug>.spec.md; component records have no
platform_of field until the next schema version; and the component id
pattern does not yet accept a language-qualified id such as
component:swift/Button. Until all three land, those other candidates are
checked only by review. pnpm check:knowledge checks a platform record
(docs/specs/components/<ComponentRoot>/<PublicName>.<language>.spec.md) as it
checks a core component record (its folder and public name, schema rules,
applicability blocks, and id), accepting its language-qualified id, and also
checks that platform_of names its core component and that its verified_by
paths exist. Its theme-target block has no core theming contract to check
against. The spec-owner gate and pnpm specs:for treat a platform record like
the core record beside it.
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.
Current enforcement gap: the example-coverage report lists each public hook that has no hook doc or no example block naming it, but it cannot see whether an example demonstrates its hook, so review checks that part of INV28. Each public hook without a conforming example is an open docs gap under INV28, tracked in the repository's issue queue.
Current enforcement gap: no repository CI check detects a new external URL in a pull request from an author outside the team (INV30). Review and merge tooling outside the repository enforces this.
Current enforcement gap: no repository check reads approvals (INV31).
pnpm check:knowledge --base <base> reports each changed approval line as a
warning and does not fail. Review and merge tooling outside the repository
requires the original decider's approval.
Current enforcement gap: .github/scripts/api-tagalong.mjs lists each added or
changed public API row outside a pull request's named scope (INV33), and lists
a row a current record decides as outside the scope without counting it as a
tag-along when its caller supplies those rows. No CI job runs the script yet,
so review sends an undecided row to an owner. The script reads API rows only:
review checks owner approval of a named row and a behavior handler change
outside the scope that adds no API row.