# Gate 02 — No undefined project shorthand

**Check:** `checks/glossary_check.py` · **Stops the build:** yes

## What this gate asserts

Every piece of project shorthand appearing in an artefact resolves to a
glossary entry.

Shorthand means four things, and the check looks for all four:

| Kind | Example | Pattern |
|---|---|---|
| Issue reference | `PROJ-142` | Letters, hyphen, digits |
| Rule or gate reference | `GATE-03`, `WS1` | Letters and digits, no spaces |
| Acronym | `PWP`, `TCC` | Two or more capitals |
| Coined compound | `LedgerSync`, `SecondLedger` | Two or more capitalised words run together |

A token that matches one of these and has no entry in `GLOSSARY.md` or in the
project's glossary table is a defect.

## Why it exists

Agents handing work to one another compress shared terminology. Each handover
is individually reasonable — the receiving agent does understand `PROJ-142`,
and spelling it out every time is genuinely wasteful. The accumulated effect
over a few dozen handovers is a body of artefacts that the pipeline reads
fluently and a human cannot read at all.

That matters because the human is supposed to be the final gate. An artefact
the final gate cannot read has removed the final gate while leaving it on the
org chart, which is worse than not having it, because everyone still believes
it is there.

The counter has to be mechanical. Asking agents to write clearly is a
preference and decays. Failing the build on an undefined term is a control.

## What a client can challenge

- *"What does this term mean?"* Every one of them is in the glossary, with a
  one-sentence definition, and defined again at first use in the artefact.
- *"Why is your glossary so long?"* Because adding a term is cheap and coining
  one silently is a build failure. A long glossary is the control working.
- *"Who decided this abbreviation?"* The change that introduced the term also
  introduced its entry. They are in the same commit.

## Known limits

This check reads patterns, not meaning. It will not catch a term that looks
like an ordinary English word but carries private project meaning — "the
ledger", "the compact", "the line". Those are caught, if at all, by gate 04 and
by the human gate. Say so to a client rather than overclaiming: the check
raises the floor, it does not guarantee legibility.

Common English capitals and standard technical acronyms are in a stop list so
the gate does not fire on `UK`, `VAT`, `PDF`, `SQL`, `API` and similar. The
stop list is visible in the check and is a legitimate thing for a client to
review.

## How it fails

```
gate-02  FAIL  reports/q3-summary.md:14  PROJ-142   (no glossary entry)
gate-02  FAIL  reports/q3-summary.md:31  LedgerSync (no glossary entry)
gate-02  FAIL  reports/q3-summary.md:52  TCC        (no glossary entry)
```

## Remediation

1. Add the term to `GLOSSARY.md`, or to the project glossary table if it will
   not outlive this project, with a one-sentence definition a client would
   accept.
2. Define it at first use in the artefact as well.
3. If the term should not exist, remove it from the artefact and consider
   adding it to the "deliberately not used" table so nobody re-coins it.
4. Re-run `python3 qa-gates/checks/run_gates.py`.

## Configuration

| Setting | Default | Where to change it |
|---|---|---|
| Glossary files | `GLOSSARY.md` plus the project glossary | `--glossary` |
| Stop list | Common English and standard technical acronyms | `STOP_WORDS` in the check |