An open source design system that's fully customizable and agent ready
TypeScript
spec(knowledge-contracts): source comments explain only non-obvious reasons (#9428)
Cindy Zhang7c84439200d7
diff --git a/AGENTS.md b/AGENTS.mdindex a4c7311029..07fd4451c4 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -158,10 +158,12 @@ For component-specific documentation, see the `{Name}.doc.mjs` file in each compDocumentation lives in two places:-1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`+1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`, in about 12 lines at most2. **Component Docs** — `{Name}.doc.mjs` files in each component directory (props, features, examples)-**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.+**Update Protocol**: When modifying code, keep the file's header comment accurate. Look for `SYNC:` comments as reminders.++**Source comments** ([`architecture:knowledge-contracts`](docs/architecture/knowledge-contracts.md#source-comments) INV29): make the code explain itself with names, structure, and control flow. A comment explains only non-obvious work: a reason, a constraint, an invariant, or a browser quirk. Never narrate the code, restate names or types, or cite pull requests, issues, dates, or spec records (`pnpm specs:for <path>` finds the record). When a citation is a file's only link to a record or claim, add that link to a record before you remove it: for a whole record, link the file through `applies_to`, `verified_by`, or `path-applicability:v1`; for a claim such as `AST-108 FR4`, add a claim-scoped reference such as `system_specs: [spec:AST-108/FR4]` to the file's own component, module, or theme record. Write in ASD-STE100 Simplified Technical English: short sentences, one topic each, active voice, present tense. Keep public JSDoc, the Effect note naming the system it syncs, and directives a tool reads: lint and TypeScript directives, `@pr-a11y` lines, and any other comment line a repository tool parses. The record has a worked before/after example.**Audience**: every `.doc.mjs`, and everything under `packages/cli/assets/docs/`, is written for people **building with** Astryx — not for people building Astryx. Internal review rubrics, readiness gates, audit checklists and lab→core criteria belong in the wiki. A public authoring-quality rubric belongs in shipped docs when callers use it to evaluate an artifact they create through Astryx and a current system spec assigns that ownership. [`packages/cli/assets/docs/README.md`](packages/cli/assets/docs/README.md) has the test and the page each kind of material goes to.diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 6831340aaf..270ac01abd 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -114,7 +114,11 @@ follows only links that records and files declare:- path fields: `applies_to`, `verified_by`, and `path-applicability:v1` patterns;- names: family `members`, design `components`, and `affects_consumer_docs` idsnaming the path's component or consumer-doc topic;-- citations: a system-spec number such as `AST-030` written in the file;+- citations: a system-spec number such as `AST-030`, or a claim such as+ `AST-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@@ -360,6 +364,80 @@ Every record is either:`architecture:template-authoring`. A public hook without a conforming exampleis 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.md` holds 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, so `pnpm specs:for <path>` lists the same records and+ cited claims before and after. A whole-record citation, such as `AST-108`,+ becomes an `applies_to`, `verified_by`, or `path-applicability:v1` link in+ the cited record. Those links reach the whole record, so they cannot keep a+ cited claim, such as `AST-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 as `system_specs: [spec:AST-108/FR4]` in the+ `Spinner` record for `Spinner.tsx`. `pnpm check:knowledge` resolves only a+ `/DEC-N` claim in a theme or module record's `references`, so a claim+ citation in a theme or module file, such as `AST-079 FR2` in+ `butterTheme.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`, and `SYNC:` 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+ `@example` fences;+ - the note on each Effect that names the external system it synchronizes+ (`architecture:react-component-runtime` INV3);+ - directives a tool reads: lint and TypeScript directives, the `@pr-a11y`+ routing lines in the header comments of browser accessibility spec files+ that `spec:AST-030` FR12 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:++```ts+// 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:++```ts+// 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.+```+## Path applicabilityUse this optional block when a record governs paths that its placement, path@@ -1192,13 +1270,14 @@ because the reader never sees the hook wired.| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/spec-owner-workflow.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; or an evaluation leaves its head without a terminal state || 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 |-| 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 |+| 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 |+| 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