check-def-title-synonyms.yml

Diff-scoped, warn-only check that flags the title of a definition div that lists synonyms with parentheses or “also called”. The lab’s rule (Ezra, 2026-10-23) is that the title is a comma list with the primary term first, as in “Logistic function, sigmoid, expit”. This implements psw#338.

A title is the first heading line inside a #def- div, or its title= attribute. The check reports a title on a line the pull request adds when it holds a parenthesis, “also called”, “also known as”, “a.k.a.”, “aka” or “or simply”. Math ($...$) and a parenthetical that contains math are ignored, so a title like Almost everywhere ($\measure$-a.e.) passes.

The check also warns when a title lists two or more names and the definition states the term twice: two display equations that each carry a defining operator (:=, \eqdef, \coloneqq, \triangleq), or prose such as “equivalently” or “in other words”. Only true synonyms, which name one concept with one definition, share a title. Equivalent but distinct concepts each get their own definition and a theorem that they agree (Ezra, 2026-10-29; psw#424). <!-- def-title-synonyms: allow --> in the definition exempts it. This second rule is a heuristic.

An untouched title is never reflagged. With no base ref the check skips instead of scanning the whole tree; whole-tree measures a corpus.

Usage

Copy examples/check-def-title-synonyms.yml to .github/workflows/ in your repository.

Inputs

Input	Default	Meaning
globs	*.qmd	Space-separated git pathspecs of tracked files to check
fail	false	Fail the workflow on a finding instead of warning
whole-tree	false	Scan every title, not only a pull request’s additions
runs-on	empty (CI_RUNNER variable, else ubuntu-latest)	Runner label; self-hosted only for a private repository
python-version	3.x	Python version to set up