ADR-0073: Authoring an explanation for a term that already has one is refused

Status: Accepted — supersedes ADR-0061 Date: 2026-09-20

Decisions

D-150 A Curated Explanation is written once per term, and authoring that term again is refused

author-explanation creates. A second authoring for a term that already has an explanation is a 409, and the refusal is the ruling rather than a gap in the command. Reviewed safety prose carrying a named reviewer and a review date is not silently overwritten by the next curator.

What this supersedes, and what it reopens

ADR-0061 is superseded, not amended. Its D-135 ruled the opposite — one live explanation per term, replaced in place by the next authoring — and stated that this had been ratified as built with no code changes. That was false when it was written. author-explanation.service.ts has create only; its P2002 becomes a ConflictError, and a docblock in it argues the opposite of ADR-0061 in terms the owner has now ruled correct: overwriting reviewed text is a second act with a second reviewer.

A cross-model grill found the contradiction on 2026-09-20 and the owner ruled the same day that the code is right.

What this reopens, stated plainly rather than left implied. ADR-0061 believed it had closed the retirement question by dissolving it — with replacement available, nothing ever needed to be taken out of service. Refusing the second authoring takes replacement away and puts the question back, in a worse form than ADR-0061 inherited it:

Nothing can correct a wrong Curated Explanation today. There is no replace, no retire and no edit. A term explained wrongly stays explained wrongly until a ruling says how it may be changed, and term @unique spanning soft-deleted rows means a soft delete would lock the term out for good.

That is an open hole, not a closed one. It is recorded here so the next agent meets it as a known gap rather than discovering it against a curator who needs a correction made.

Context

The question ADR-0061 answered is real: a term is explained, and the explanation turns out to be wrong or thin. ADR-0061 answered it by making the second authoring a replacement, and reasoned that this was safe because a published version keeps its own copy (D-127), so a replacement cannot reach a version already shipped.

That reasoning is sound about published versions and silent about the live store, which is what the next curator reads and what the next publish will carry. The owner's ruling is about the act, not the payload: an explanation is reviewed prose with a named reviewer and a date on it, and a command that lets the next curator overwrite it without either of those changing hands is a command that loses a named judgement. The product refuses that elsewhere for the same reason — a Reconciliation is not overwritten either, and RECONCILIATION_EXISTS is its refusal.

Decision

author-explanation refuses a term that already carries an explanation. Correcting an existing explanation is not possible and is not ruled here.

Rejected options

• Replacing the live explanation in place, recording the new reviewer and time — rejected by the owner on 2026-09-20. This was ADR-0061's ruling. It loses because reviewed safety prose carrying a named reviewer and a review date is not silently overwritten by the next curator: the act of correcting someone's reviewed judgement is a second act, and a create that quietly becomes an update records it as neither.
• Building a correction path in the same ruling that refuses the overwrite — not taken here. The refusal is what was ruled; how a wrong explanation is corrected is a question nobody has answered, and answering it inside this ADR would settle by implementation the thing the supersession just showed is worth ruling on. It is recorded above as an open hole instead.

This ruling may not be re-decided

If a change contradicts this ADR: stop and raise it. Do not implement over it.

Specifically: do not turn author-explanation into an upsert, do not add a replace or edit path without a ruling, and do not soft-delete an explanation to free its term — term @unique spans soft-deleted rows, so that locks the term out permanently rather than freeing it.

Consequences

What becomes true. An explanation with a named reviewer on it stays as that reviewer left it. The command's behaviour and the ruling agree, which they did not before.

What this costs. A wrong explanation cannot be corrected at all, which is the open hole above and is the price of the refusal until a correction path is ruled.

What is closed off. Replacement in place, and any implicit upsert.

Coverage

Upstream	Landed in	Evidence	Note
D-90	D-150	a term explanation is a Curated Explanation, curated and displayed extractively, so the live row carries a reviewer whose judgement the refusal protects	ADR-0037
D-127	D-150	ADR-0061 reasoned from the published payload keeping its own copy; that is true and is not what the ruling turns on, which is the act rather than the payload	ADR-0056; recorded so the superseded reasoning is not re-derived