# Gate 04 — The artefact is legible to a human outside the pipeline

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

## What this gate asserts

An artefact can be read by a competent person who is not part of the pipeline
that produced it.

Four crude measures, each with a threshold:

| Measure | Default threshold | What it catches |
|---|---|---|
| Undefined shorthand density | ≤ 1.5% of words | Terms the reader has to look up and cannot |
| Total shorthand density | ≤ 6% of words | Prose that is technically defined and still unreadable |
| Mean sentence length | ≤ 32 words | Accumulated clauses from successive agent edits |
| Very long sentences | ≤ 10% over 45 words | The specific failure above, concentrated |

## Why it exists

This is the human gate expressed as a number.

The failure it guards against is quiet. Nobody decides to produce an illegible
document. It happens because each agent in a chain makes a locally sensible
compression — an abbreviation here, a clause appended rather than a sentence
rewritten there — and no single step is wrong. By the eighth handover the
artefact is fluent to the pipeline and opaque to the person who is meant to
approve it.

That person will usually approve it anyway. Admitting you could not follow a
document is socially expensive, and the document looks authoritative. So the
control has to fire before the document reaches them, which means it has to be
mechanical and it has to run on every artefact.

## Deliberately crude

These are word counts and ratios. They do not measure comprehension and they
are not trying to.

The point is that the check exists and fires, not that it is clever. A
sophisticated readability model would be more accurate, harder to explain to a
client, and impossible for them to challenge. A ratio of undefined terms to
words is something a client can recompute by hand on a page they are suspicious
of, which is worth more than accuracy here.

It follows that this gate has both false positives and false negatives. A
dense but well-written technical passage may fail. A vacuous passage of short
plain sentences will pass. Neither is a reason to remove the gate; both are
reasons not to describe it as a guarantee.

**Artefacts under 80 words are skipped.** A ratio over two sentences tells you
nothing, and firing on it would train people to ignore the gate. The
consequence is a real blind spot: a very short artefact can be dense with
undefined shorthand and this gate will not see it. Gate 02 still fails on the
terms themselves, which is the cover — but if a project's deliverables are
routinely short, say so and lower the floor rather than assuming it is covered.

## What a client can challenge

- *"Show me the score for this document."* The check prints per-file numbers
  against each threshold.
- *"Your threshold seems arbitrary."* It is. It was set where it caught the
  documents we already knew were bad. Changing it is a project-procedures
  amendment with a stated reason, and "the gate was noisy" is not one.
- *"Did a human actually read this?"* The gate does not assert that. It asserts
  the document was readable. Whether it was read is a sign-off question.

## How it fails

```
gate-04  FAIL  handover/draft-3.md
           undefined shorthand   3.10%  (threshold 1.50%)  PROJ-142, LedgerSync, TCC
           mean sentence length  38.4   (threshold 32.0)
           long sentences        14.0%  (threshold 10.0%)
```

## Remediation

1. **Undefined shorthand.** Define the terms, or stop using them. This overlaps
   gate 02 by design: gate 02 fails on any undefined term, gate 04 fails on the
   density of them, and an artefact can pass one and fail the other.
2. **Sentence length.** Split the sentences. Sentences that grew by accretion
   across several edits usually contain two claims that want separating.
3. **If the artefact is genuinely dense and correct** — a specification, a
   query catalogue — record an exclusion in the project working procedures,
   with a reason and a review date. Do not raise the global threshold to make
   one file pass.
4. Re-run `python3 qa-gates/checks/run_gates.py`.

## Configuration

| Setting | Default | Where to change it |
|---|---|---|
| Undefined shorthand density | 1.5% | `--max-undefined` |
| Total shorthand density | 6.0% | `--max-shorthand` |
| Mean sentence length | 32 words | `--max-sentence` |
| Long-sentence share | 10% over 45 words | `--max-long-share` |