ADR-005. Generated documentation is refused, not reported

Status: accepted, 5 September 2026. Still in force.

Context

The criterion for a published module is one sentence:

Every published module must be understandable and usable from its Galaxy page alone, without reading the OpenAPI contract or the source.

A generator meets that criterion badly by default. It copies field descriptions from the contract, and the contract sometimes says description: snapshot_id. It falls back to str for an array with no declared item type. It emits an example with a placeholder where the enum’s own values were available. Each of those is defensible on its own and unusable in aggregate, and a release went out carrying a hundred fallback sentences in its RETURN blocks.

Reporting them was not enough. The report was read when someone chose to read it, which is to say after the release.

Decision

scripts/docs_quality.py names each documentary defect, and every one of them blocks. Fallback phrasing, placeholders, an operation identifier leaking into prose, HTTP vocabulary in a description, an example that cannot be copied as is, a returned key with no described fields: none of these is a warning.

The gate runs in mise run check, not only in release:check. It was in release:check alone, which is the moment when refusing costs a version number rather than a round trip.

The inventory plugin is measured too. It is a published page like any other.

Consequences

Adding a product can turn the gate red for reasons that have nothing to do with the code: a contract whose descriptions are poorer than the previous one. That is the intended behaviour. The fix is an override carrying its reason, not a loosened rule.

The counters this gate produces are published in derived blocks, regenerated by scripts/readme_counters.py and refused when stale, so that no measured number in a published document is ever typed by hand.

What this record does not decide

Whether the module works. Documentation being usable and behaviour being correct are different claims, see ADR-006.