# AGENTS.md — binding repository contract

This file is the contract for any agent or human working **inside the Triage
Design System repository**. `README.md` explains how to consume the system; this
file explains how to change it. Repo rules below override habit.

## Generated files are never hand-edited

These paths are written by tools and must be regenerated, not edited:

| Generated path | Written by | Regenerate with |
|---|---|---|
| `core/base.css`, `core/patterns.css` | `tools/build_core.py` | `python3 build.py core` |
| `tokens/tokens.css` | `tools/build_tokens.py` | `python3 build.py tokens` |
| `spec/token-consumers.json` | `tools/token_map.py` | `python3 tools/token_map.py` |
| `icons/sprite.svg`, `icons/icons.json` | `tools/build_icons.py` | `python3 build.py icons` |
| `brand/*` | `tools/build_brand.py` | `python3 tools/build_brand.py` |
| `exports/*` | `tools/export_tokens.py` | `python3 build.py exports` |

Edit the source, then regenerate:

- **Core stylesheets:** edit `src/core/{base,additions,components,patterns}.css`
  and run `python3 build.py core`. `src/core/` is canonical.
- **Tokens:** edit `tokens/tokens.json` and run `python3 build.py tokens`. Every
  colour/typography/spacing/motion value the CSS consumes is a custom property
  from `tokens.css`; no raw hex, px scale dupe, physical direction property or
  ad-hoc duration belongs in `core/`. Font stacks are derived from
  `typography.family-*`; the root is the relative `--base-size` and the `--fs-*`
  design scale divides by the same `typography.base-size`, so the authored px and
  the root share one source; compact-density values live per token in
  `$extensions.com.triage.compact` and `tools/build_tokens.py` emits the
  `:root[data-density="compact"]` block (never hand-write density overrides in
  `src/core/`); and media
  queries in `src/core/` use `{bp-*}` placeholders that `tools/build_core.py`
  resolves from `misc.breakpoint`. Spacing has a curated preferred scale
  (`2/4/8/12/16/24/32/48`) plus semantic roles (`page`/`card`/`field`/`control`,
  emitted as `--space-*`) that primitives consume by intent; fixed chrome/column
  widths live in `misc.layout` and emit as `--layout-*`. Legacy/fine spacing steps
  stay emitted for compatibility but are labelled legacy — prefer the preferred
  scale for new work. Adding an emitted token requires a documented
  consumer or a reason in `spec/token-metadata.json` — `tools/token_map.py`
  fails otherwise.

Commit generated output in the same commit as its source change.

## Gates (run before declaring work done)

```bash
python3 build.py check                    # core/token sync, DTCG, rename sweep, spec, lint tests
python3 lint/triage_lint.py . --strict    # dogfood the linter on this repo (must be 100/100)
python3 tests/browser/run.py              # behaviour + contrast + UI baseline (needs Chrome)
python3 tests/browser/run.py --update-baseline   # regenerate metrics/ui-baseline.json
```

`build.py check` includes `tools/build_core.py --check` and
`tools/token_map.py --check`, so a stale `core/*.css` or an unjustified token
fails CI. Never suppress a lint finding without a documented reason.

`tests/browser/run.py` also gates the deterministic UI baseline: it measures a
fixed selector list on `examples/{dashboard,list,form,viewer}.html` and the
generated overlays docs page (three theme/density variants × 1440/390) and
compares computed styles plus one fixed-size geometry box against the committed
`metrics/ui-baseline.json`, failing by element name on drift. Only regenerate the
baseline deliberately (`--update-baseline`) when the visual change is intended;
it prints a per-screen/element summary, and the diff is reviewable generated
output — read it before committing rather than treating it as a silent artifact.
The page-hierarchy contract (levels → elements → tokens, do/don't) is documented
in the typography page source (`site/pages_foundations.py`, `/foundations/typography`).

## Spec and lint rules

- `spec/states.json` is the component lifecycle/state contract. Each component
  carries a `status` (`stable`/`beta`/`experimental`/`deprecated`) and a
  `verify` list of selectors that `tools/verify.py` checks against `core/*.css`.
- The top-level `lifecycle` object defines the **evidence** each status requires.
  `stable` means behavioural regression coverage exists (the interactive states
  are exercised in `tests/browser/`), **not merely selector presence**.
- Adding or changing a lint rule takes three coordinated edits: the rule in
  `spec/rules.json`, its implementation in `lint/engine.py`, and tests under
  `lint/tests/` (plus a mutation/fixture proving the rule fires).

## Provenance policy

- `src/core/` is canonical. `tools/assemble_from_pack.py` and
  `tools/tokenize_core.py` are historical provenance tooling: they refuse to run
  without `--force` and `assemble_from_pack.py` stages its output under
  `dist/pack-sync/` — **no normal build path overwrites `core/` or `tokens/`**
  from the external pack.
- `.provenance.json` records the input/output hashes of the last pack sync;
  `PROVENANCE.md` records lineage. Update them only through the (forced)
  provenance tools or when correcting a now-false claim.

## Scope discipline

- Keep changes scoped to your assigned worktree/branch; never force-push, and
  never edit another checkout.
- Keep real data read-only; put scratch files under `/tmp`.
- A change to a **public class or token name** is a breaking change: it needs a
  `CHANGELOG.md` note and a migration path (see `RENAME-MAP.md`).
