check-exercise-background.yml
Diff-scoped check, blocking by default, that flags an exercise whose title names a defined term that its body never mentions. The lab’s rule (Ezra, 2026-10-29) is that an exercise body gives the background its title implies: for “Maximizing a gamma-family kernel”, the body says what a gamma distribution and its kernel are, links them, and says why anyone maximizes one.
The check looks at each exercise div (#exr-...) with a heading title. It reports only a run of title words that matches a whole defined term, meaning a phrase from some #def- title in the scanned files, so “times” is not read as part of “time series” and a word with no definition is never reported. A definition title that names aliases, such as “Gradient (also called del)”, defines each of them. When the scanned files hold no #def- titles, the check prints a notice and reports nothing.
The body includes the text of every div the exercise cites or links, such as @exr-..., @def-..., @thm-..., or @sol-..., followed from one cited div to the next. A cited exercise lends its text but not its solutions. An exercise that cites an exercise the scanned files do not hold is skipped, since its background is elsewhere, and so is a part that builds on an earlier exercise (“Use the setup of @exr-…”). A math macro says the word its name begins, so \grad says gradient, a few short macros say a listed word, so \E says expected, and words inside \text{}, \operatorname{}, and \mathrm{} count as body words. A title word counts as present when a word in the body shares its first five letters, so “Maximizing” matches “maximum”, or when its singular form does. Generic task verbs such as find, compute, expand, and classify, math in the title, code fences, and HTML comments are ignored.
Whole-tree runs on the lds, mds, pds, sds, and psw notes left only titles that name a term the body never states (gha#1481), so the check fails by default. A title word that the body gives only through a synonym or through notation is still reported: say the word in the body, with its link, or reword the title. Set fail: false to warn instead.
An untouched exercise 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-exercise-background.yml to .github/workflows/ in your repository.
Inputs
| Input | Default | Meaning |
|---|---|---|
globs |
*.qmd |
Space-separated git pathspecs of tracked files to check |
fail |
true |
Fail the workflow on a finding; false warns instead |
whole-tree |
false |
Scan every exercise, not only a PR’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 |