# naming Guardrails

> Canonical path: `guardrails/naming/README.md`

This directory owns focused checks for ambiguous terminology that has a
reviewed, more precise domain replacement.

- [`semantic-terminology.sh`](./semantic-terminology.sh) rejects only retired
  identifier families such as `SurfaceNotification*` and
  `RepoRoleCanonical`.
- [`retired-ambiguous-identifiers.txt`](./retired-ambiguous-identifiers.txt)
  records each reviewed family and its preferred terminology.
- [`semantic-terminology-exceptions.txt`](./semantic-terminology-exceptions.txt)
  records exact code identifiers required by frozen generated contracts; stale
  entries fail the check.
- [`scan-identifiers.py`](./scan-identifiers.py) supplies the code-only lexer
  used by the check, excluding comments and quoted protocol literals.

This is intentionally **not** a repository-wide ban on the words `surface` and
`canonical`. Genuine UI/rendering surfaces, canonicalization algorithms,
standard-library APIs, and frozen client/wire/storage contracts keep their
existing names. Whether a newly encountered use is ambiguous is a semantic
review decision, not a token-count target.