An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): assign the caller quality rubric (#7257)
Joey7ec95640bc28
diff --git a/docs/specs/AST-041-consumer-docs-audience/spec.md b/docs/specs/AST-041-consumer-docs-audience/spec.mdindex 6251edbf81..3d85f6cf51 100644--- a/docs/specs/AST-041-consumer-docs-audience/spec.md+++ b/docs/specs/AST-041-consumer-docs-audience/spec.md@@ -7,13 +7,13 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: josephfarina-approved_at: 2026-09-23+approved_at: 2026-10-09phase: acceptedowners: [josephfarina]affects_architecture: []affects_families: []affects_contributing: []-affects_consumer_docs: []+affects_consumer_docs: [is-my-code-good]---# Consumer documentation audience boundary system spec@@ -41,12 +41,15 @@ consumer surfaces, including docs that integrations contribute.- **FR1 — Shipped docs are for callers.** Every section of a shipped doc MUSTdescribe something a caller can use or rely on: purpose and alternatives, APIand defaults, observable behavior and its guarantees, composition, costs and- obligations the caller inherits, theming seams, or migration.+ obligations the caller inherits, theming seams, migration, or quality criteria+ they can apply to a product surface or artifact they create with Astryx from+ public evidence.- **FR2 — Maintainer process is excluded.** A shipped doc MUST NOT ask its reader- to produce review evidence, meet grading or promotion criteria, follow Astryx's- contribution lifecycle, or run Astryx's own test and CI tooling. That material- belongs in the contributor surface that owns the topic, or in the contributing- guide when no specific surface exists. It never defaults back to a shipped doc.+ to produce evidence for Astryx maintainers, meet Astryx's internal grading or+ promotion criteria, follow Astryx's contribution lifecycle, or run Astryx's own+ test and CI tooling. That material belongs in the contributor surface that owns+ the topic, or in the contributing guide when no specific surface exists. It+ never defaults back to a shipped doc.- **FR3 — System guarantees stay, as guarantees.** A fact about the system'sbehavior that a caller can rely on MUST stay in shipped docs, stated as aguarantee to the caller. For example, "theme targets are stable once@@ -68,6 +71,12 @@ consumer surfaces, including docs that integrations contribute.- **FR6 — Contributed docs follow the same boundary.** Docs that an integrationcontributes to consumer surfaces MUST meet FR1–FR4. The integration authoringreference MUST state this rule.+- **FR7 — The shared caller rubric has one owner.** The shipped `is-my-code-good`+ guide MUST own the shared criteria for whether caller-created product code uses+ Astryx well. Specialized rubrics MAY add weights and artifact-specific checks,+ but MUST link to the shared criteria instead of redefining them. A caller rubric+ MUST use public inputs and MUST report missing evidence as uninspected, not as a+ pass.### Platform support@@ -79,10 +88,12 @@ consumer surfaces, including docs that integrations contribute.The shipped topic directory has a README that states the caller-action test,common signs of maintainer writing, and where that material goes. Repository-instructions state the same audience. No automated check enforces the boundary-yet. The authoring types declare a distribution audience field with public and-internal values for the docs graph; nothing reads it yet. FR4 keeps that field-separate from the reader boundary.+instructions state the same audience. FR7 assigns the shared caller-facing+rubric to `is-my-code-good`; its guide and the specialized links are companion+implementation outside this specification-only change. No automated check+enforces the audience boundary yet. The authoring types declare a distribution+audience field with public and internal values for the docs graph; nothing reads+it yet. FR4 keeps that field separate from the reader boundary.This specification-only change alters no runtime behavior or published packageand needs no Changeset.@@ -95,6 +106,7 @@ and needs no Changeset.| FR4 | Compiled public and internal bundle tests | public doc, internal doc, maintainer material marked internal | Maintainer material appears in any bundle || FR5 | Check fixtures and a run over the shipped corpus | clean corpus, real violation, caller instruction with a flagged term, exemption | The corpus fails, the violation passes, the caller instruction fails, or an exemption is silent || FR6 | Integration doc fixtures | contributed topic that addresses maintainers | A contributed doc bypasses the boundary |+| FR7 | Docs graph and rubric review | shared code rubric, specialized template scoring, missing rendered evidence | Shared criteria have two owners, a specialization does not link, or missing evidence passes |## Decision log@@ -123,6 +135,19 @@ with maintainer process.Rejected: a bare word list as a gate, and a distribution audience used as aplace for maintainer material.+### DEC-3 — Caller-owned quality review stays in shipped docs++**Reference:** `spec:AST-041/DEC-3`+**Decider:** `josephfarina`, `2026-10-09`++A person or agent building with Astryx can act on public criteria that evaluate+its own product code. The `is-my-code-good` guide owns the shared criteria;+artifact-specific guides link to it and add only their own checks or scoring.+Missing evidence remains visible instead of becoming a pass.++Rejected: treating every quality rubric as maintainer process, and copying the+shared criteria into each artifact-specific guide.+## Open questionsNone.