ADR-070: A decision is stated for what it chooses; a prohibition is reserved for a constraint that has been verified
Status Active · Filed 2026-09-03
Context
A decision document is read far more often than it is written, mostly by someone deciding whether a rule applies to the case in front of them. A title that says never settles that question before the body is opened. When the mechanism enforces no such thing — or the constraint has an exception the author did not check — the reader inherits a rule the record does not actually keep.
Three drafts in one day did this. The typed-edges decision’s title said a successor is never inferred from prose, where the decision was that fields are preferred and prose allowed (#143). The first draft of ADR-069 said a workflow file never cites a temporary code, where the constraint belongs to one token and a person can edit the file freely (#150). Each was sent back in review with the same note; a guard that keeps catching the same thing is a bug report about the workflow, so the note becomes a decision the review can cite.
Decision
A decision is stated for what it chooses. The title and the decision paragraph say what is preferred and what is done. What was rejected is named under alternatives, as a rejection.
A prohibition is reserved for a constraint that has been verified. “Never”, “must not”, “forbidden” and their kin appear in a title or a decision paragraph only where the author has checked the constraint against the thing that enforces it — a platform’s refusal, a lint error, a type — and the text names that enforcer. A constraint on one actor (the generation job’s token) is stated for that actor, not for the file.
The record’s “X, not Y” titles — reported, not enforced; populated, not demanded — name the rejected alternative beside the choice, and are the affirmative form.
Alternatives considered
- A lint for the words. A rejected-alternative list says “never” legitimately, and so does a verified constraint; telling them apart is the judgement this decision asks the author to make, and a check that fires on the word would catch the right cases with the wrong ones.
- Leave it to review. That is where it was caught, three times, by the same reviewer with the same note. Writing it down is what lets the next review point instead of explain.
Consequences
Existing decisions keep their wording; a title is corrected when its decision is next revised, not in a sweep. A reviewer sending a draft back for a “never” cites this decision. The two drafts that prompted it were reworded before they merged.