Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: make review context subordinate to specs (#6292)

Cindy Zhang4a0d1d1e2bc1
diff --git a/.github/PULL_REQUEST_TEMPLATE/bug-fix.md b/.github/PULL_REQUEST_TEMPLATE/bug-fix.md
index bb06f03134..39cd41ed81 100644
--- a/.github/PULL_REQUEST_TEMPLATE/bug-fix.md
+++ b/.github/PULL_REQUEST_TEMPLATE/bug-fix.md
@@ -2,7 +2,11 @@
## User impact
-<!-- Who encounters the defect, in what state, and what fails? -->
+<!-- Who encounters the defect, in what supported state, what fails, and what does the restoration enable or prevent? -->
+
+## Problem and solution fit
+
+<!-- Ask why three times: why does the defect occur, why does it harm the task, and why does that harm matter? Explain how the narrow fix addresses that chain. -->
## Expected behavior and authority
diff --git a/.github/PULL_REQUEST_TEMPLATE/new-feature.md b/.github/PULL_REQUEST_TEMPLATE/new-feature.md
index 95760f3bb7..cfe90d6f23 100644
--- a/.github/PULL_REQUEST_TEMPLATE/new-feature.md
+++ b/.github/PULL_REQUEST_TEMPLATE/new-feature.md
@@ -2,15 +2,19 @@
## User need
-<!-- Who needs this capability, in what state, and why existing composition does not solve it? -->
+<!-- Who needs this capability, in what supported state, what does it enable or prevent, and why does existing composition not solve it? Ask why three times until the user or builder harm is concrete. -->
+
+## Problem and solution fit
+
+<!-- Explain how each primary or supporting delta addresses the need. Remove or split any independently useful tagalong. -->
## Current specification
<!-- Link the current owner and exact decision admitting the capability and any public API. -->
-## Public delta
+## Public delta and caller burden
-<!-- List observable behavior, API/types/defaults, compatibility, theming, and accessibility changes. Include representative consumer syntax when API changes. -->
+<!-- List observable behavior, API/types/defaults, compatibility, theming, and accessibility changes. Include representative before/after callsites and every additional decision the caller must understand or make. -->
## Design and alternatives
diff --git a/.github/PULL_REQUEST_TEMPLATE/other.md b/.github/PULL_REQUEST_TEMPLATE/other.md
index d25729c90d..5979e3e2f9 100644
--- a/.github/PULL_REQUEST_TEMPLATE/other.md
+++ b/.github/PULL_REQUEST_TEMPLATE/other.md
@@ -6,7 +6,11 @@
## User or maintainer impact
-<!-- Who is affected, in what state, and what changes? -->
+<!-- Who is affected, in what supported state, what behavior changes, and what does that enable or prevent? -->
+
+## Problem and solution fit
+
+<!-- Ask why three times, map every primary/supporting delta to the problem, and identify removable tagalongs. If public API changes, show before/after callsites and added caller decision burden. -->
## Authority
diff --git a/.github/PULL_REQUEST_TEMPLATE/specification.md b/.github/PULL_REQUEST_TEMPLATE/specification.md
index 669ac0ddac..5ac9892cc3 100644
--- a/.github/PULL_REQUEST_TEMPLATE/specification.md
+++ b/.github/PULL_REQUEST_TEMPLATE/specification.md
@@ -10,7 +10,7 @@
## Decision
-<!-- State the approved requirement, conditions, defaults, exceptions, compatibility, and owner. -->
+<!-- State the approved observable requirement: supported inputs, outputs/states, failure or degradation behavior, defaults, exceptions, compatibility, and owner. Preserve implementation freedom. -->
## Rejected alternatives
@@ -27,7 +27,11 @@
## Scope
- [ ] This PR contains specification records only.
+- [ ] It records observable behavior and preserves equivalent internal implementations.
+- [ ] Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
+- [ ] Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
- [ ] It records one intentional durable decision, not a review transcript or rescue for a separable tagalong.
+- [ ] The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
- [ ] Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
- [ ] Public text and artifacts contain no internal Meta context.
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 33131d6723..138202ce50 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -9,7 +9,14 @@ superseded_by: null
approved_by: cixzhang
approved_at: 2026-08-30
owners: [cixzhang]
-applies_to: [AGENTS.md, docs/, packages/core/src/, packages/lab/src/]
+applies_to:
+ [
+ AGENTS.md,
+ .github/PULL_REQUEST_TEMPLATE/,
+ docs/,
+ packages/core/src/,
+ packages/lab/src/,
+ ]
verified_by:
[
scripts/check-knowledge.test.mjs,
@@ -153,6 +160,42 @@ Every record is either:
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.
+- **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.
## Writing specifications and contracts
@@ -489,17 +532,77 @@ 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.
+
## 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 |
-| 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 |
+| 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 |
+| 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 |
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,
diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.md
index 4848c8610d..645f53c4d5 100644
--- a/docs/contributing/pull-requests.md
+++ b/docs/contributing/pull-requests.md
@@ -14,6 +14,25 @@ GitHub uses the default template automatically. To choose another, add `?templat
| Change tooling, tests, CI, or repository maintenance | `maintenance.md` | operational problem, failure proof, success proof, unchanged product behavior |
| Anything else | `other.md` | primary intent, user or maintainer impact, authority, evidence |
+## Explain only what authority does not already say
+
+The pull request and current records are the first source for context. Do not copy
+them into another summary. Fill only what is missing:
+
+- Trace the problem through three why questions: why it occurs, why it harms the
+ affected task, and why that harm matters.
+- Map the proposed solution and every primary or supporting delta back to that
+ problem. Remove or split a tagalong that does not clearly contribute.
+- State who is affected, in what supported state, and what behavior the change
+ enables or prevents.
+- When public API changes, show representative before and after callsites,
+ defaults and compatibility, and every additional decision the caller must make.
+
+These explanations help reviewers apply current authority; they do not create it.
+Product behavior remains owned by the applicable current component, module,
+family, design, theme, architecture, or system record. API caller burden follows
+`spec:AST-002`.
+
## Keep the intent atomic
Before requesting review, partition every observable delta:
diff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.md
index a668c2a51a..b20f872b50 100644
--- a/docs/specs/AST-002/spec.md
+++ b/docs/specs/AST-002/spec.md
@@ -157,6 +157,13 @@ A public API proposal is admitted only when it passes both gates:
gap requires owner judgment. Implementation convenience, removal of an internal
wrapper, or exposure of existing internal fields is not evidence that an API should
exist.
+- **FR20 — Callsite impact and decision burden are explicit.** A public API change
+ shows representative before and after callsites, including defaults and
+ compatibility, and names every new choice the caller must understand or make. That
+ burden is admitted only when FR1 proves the distinction is caller-owned, the
+ component cannot derive it under FR2, and the choice has predictable meaning under
+ FR7–FR10. Review-generated impact prose is context only; it cannot supply missing
+ caller ownership or authorize the API.
### Platform support
@@ -243,6 +250,7 @@ still determine whether the implementation satisfies it.
| FR15 | Type-level constraints plus runtime validation and behavior tests | invalid values, unsupported combinations, and legitimate composition | The API silently renders a broken state or prevents a valid composition |
| FR16 | Full value-domain, input-shape, and parallel-combination contract review | semantic variants, raw or palette values, explicit overrides, and defaults | One value or shape switches the controlled axis, or a parallel input silently changes precedence |
| FR17 | Public module/utility export inventory plus implementation, test, consumer, and release-history review | construction, inspection, lookup, conversion, registration, hooks, and released compatibility | A verb hides the returned value or side effect, two public roles are fused, a non-hook utility uses `use*`, or a released mismatch is silently renamed |
+| FR20 | Public callsite and caller-burden review | representative before/after callsites, defaults, compatibility, and every caller-owned choice | A new caller decision is hidden, derivable, unpredictable, or justified only by review prose |
| FR18 | Multi-caller composition scenarios plus owning-contract review | shared semantic operation, internal-only mechanism, and two representative consumers | Product builders cannot compose stable behavior, or implementation fields are exposed without caller-owned semantics |
| FR19 | Bug-fix before/after authority diff plus public-surface and behavior inventory | pure restoration, restoration plus separable novel API/visual change, and internal-wrapper removal | A bug-fix label bypasses authority, a removable tagalong forces a broader spec, or internal mechanics become public because exposure is convenient |
| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |
@@ -405,6 +413,19 @@ other existing fields merely because removing an internal wrapper or fixing one
path becomes easier. Existing implementation is evidence of mechanics, not intent
for permanent public API.
+### DEC-9 — Caller decision burden must be visible and justified
+
+**Reference:** `spec:AST-002/DEC-9`
+**Decider:** `cixzhang`, `2026-09-12`
+
+A public API proposal shows the callsite before and after the change and names each
+new decision a caller must make. The decision is admitted only when it represents
+caller-owned intent the component cannot derive and its outcome remains predictable
+across defaults, combinations, and supported states.
+
+Rejected: treating a shorter implementation, a persuasive user-impact summary, or
+a completed review checklist as proof that callers should own another choice.
+
## Open questions
None.
diff --git a/docs/templates/knowledge/architecture.md b/docs/templates/knowledge/architecture.md
index 447fa095eb..0cdbfdcb31 100644
--- a/docs/templates/knowledge/architecture.md
+++ b/docs/templates/knowledge/architecture.md
@@ -22,6 +22,8 @@ deciding_specs: [spec:AST-000/DEC-0]
## Boundaries and invariants
+<!-- Architecture records own internal responsibility, seams, and mechanisms needed to satisfy deciding specs. They MUST NOT broaden the observable product contract beyond those current decisions. -->
+
- **INV1 — `<invariant>`.** `<What MUST remain true in the shipped system.>`
## Change coupling
@@ -34,7 +36,7 @@ deciding_specs: [spec:AST-000/DEC-0]
## Deciding specs
-- `spec:AST-000/DEC-0` — `<decision>`
+- `spec:AST-000/DEC-0` — `<observable behavior decision; architecture records never treat implementation evidence as product authority>`
## Verification
diff --git a/docs/templates/knowledge/system-spec.md b/docs/templates/knowledge/system-spec.md
index 2c5c0a3345..c15d2e4d1b 100644
--- a/docs/templates/knowledge/system-spec.md
+++ b/docs/templates/knowledge/system-spec.md
@@ -20,41 +20,54 @@ affects_consumer_docs: [<doc-id>]
## Intent
+<!-- State the person/task and the durable observable outcome this spec owns. -->
+
## Non-goals
-- `<non-goal>`
+- `<adjacent behavior this decision does not settle>`
+- Equivalent internal implementations remain valid when they satisfy this contract.
+- Internal modules, files, function names, algorithms, data structures, storage
+ layouts, manifests, journals, locks, transaction protocols, and CI job/workflow
+ topology belong in architecture or implementation unless callers or
+ interoperating systems intentionally depend on that exact mechanism as a public
+ protocol. In that case, state who depends on it and why an equivalent
+ implementation would not satisfy the contract.
## Requirements
-- **FR1 — `<behavior>`.** `<The system MUST …>`
-- **IR1 — `<constraint>`.** `<The implementation MUST …>`
+<!-- Contract supported inputs, observable outputs/states, failure or degradation behavior, defaults, exceptions, compatibility, and caller-visible ownership. -->
+
+- **FR1 — `<observable behavior>`.** `<The system MUST expose or preserve …>`
### Platform support
- Supported feature/engine floor: `<matrix or canonical consumer-doc link>`
- Unsupported behavior: `<required fallback, graceful degradation, or prohibition>`
-- Browser evidence: `<real browser requirement; do not substitute Playwright WebKit for Safari>`
+- Browser evidence: `<evidence layer needed to prove the observable claim; do not prescribe a CI job or workflow name>`
## Current-state impact
-<!-- Name every architecture, family, contributing, and consumer-doc surface changed when this ships. -->
+<!-- Name every architecture, family, contributing, and consumer-doc surface changed when this ships. Link architecture records that own internal seams; do not duplicate their mechanisms here. -->
## Verification
+<!-- Verification proves the observable contract. It does not authorize an internal architecture or CI topology. -->
+
| Contract | Verification | Representative states | Mutation or failure expectation |
| -------- | -------------------- | --------------------- | ------------------------------------- |
| FR1 | `<test or evidence>` | `<states>` | `<removing behavior makes this fail>` |
## Decision log
-### DEC-1 — `<decision>`
+### DEC-1 — `<behavioral decision>`
**Reference:** `spec:AST-000/DEC-1`
**Decider:** `<person>`, `<YYYY-MM-DD>`
-`<Reason and user impact.>`
+`<Reason, user impact, and observable contract.>`
-Rejected: `<alternative — why>`.
+Rejected: `<consequential behavioral alternative — why>`. Do not record a private
+implementation merely because it supplied the evidence.
## Open questions