diff --git a/AGENTS.md b/AGENTS.md index 615f10f..064eaca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,13 +22,30 @@ Resolve references inside either skill relative to its own directory. Hosts should point agents to `packages/ui/AGENTS.md`; they do not need to copy, forward, symlink, or separately register these skills under `.agents/skills`. -## Enforcement is three layers +## Enforcement is three layers (plus one narrow fourth) | Layer | Where | Role | |---|---|---| | **Tokens** | `src/style.css` (`@theme inline` / `:root` / `.dark`) | the ONLY place raw values live | | **This contract** | `packages/ui/AGENTS.md` | the rules + rationale | -| **Guard** | `scripts/check-ui-contract.mjs` (wired into `mise run lint`) | mechanical block on drift | +| **Guard** | the HOST repo's `scripts/check-ui-contract.mjs` (wired into `mise run lint`) | mechanical block on drift | +| **DOM tests** | `src/**/__tests__/*.test.ts` (`pnpm test`) | only for promises the three above CANNOT see | + +The guard lives in the **consuming repository**, not here — it scans `packages/ui` +and `apps/web` together and keeps its ratchet baselines beside itself, so +`node scripts/check-ui-contract.mjs` does not run from a standalone clone of +this module. Its rules are still binding on every line written here; run it from +the host before landing anything, and add new rules there (§ Extending this +contract). + +The fourth layer is **deliberately tiny and must stay that way.** All three +layers above read SOURCE TEXT, which makes them structurally blind to exactly +one defect class: a composition that type-checks, whose class strings are all +legal, but whose RENDERED DOM puts them on the wrong element. `