ADR-105: A mention is not a citation, and says nothing about status

Context

Every acknowledgement luria has asserts something about a code’s state. inactive-ok says the document is not in force; unresolved-ok says the code resolves to nothing. That is deliberate and it is why they retire correctly: the state changes, the claim stops being true, and luria lint reports the annotation as no longer applying.

But some references name a code without claiming anything about it. ADR-093 quotes three codes as specimens — evidence for a decision about fixture namespaces. ADR-046’s prose is about the literal spelling DP-17 and the regex branch that did not match it. migrate.py uses a code to demonstrate what a moved document’s old address looks like. None of these asserts that the document is retired, or absent, or anything else. They are mentions.

Today they are written as unresolved-ok, which is the closest available word and is false: it claims the code resolves to nothing, which is true only until somebody writes that document. Then the acknowledgement goes stale for a reason that has nothing to do with why it was written, and — because scan drops an annotation with a problem whole — takes every other code in the same annotation down with it.

This is not hypothetical. The DP scheme is at 17; DP-018 is the next number and two acknowledgements name it today. DP-017 already did exactly this: the principle was written, three acknowledgements went stale, and one of them silently stopped excusing four unrelated citations until it was noticed a week later.

Decision

A third acknowledgement, mention-ok:, says a code is named, not cited — the text makes no claim about the document’s state. It suppresses both the retired-citation and the unresolved-code finding at its sites.

The load-bearing part is what “still applies” means for it. Every other acknowledgement is used when it suppresses a finding, so it falls out of use exactly when the state it asserts stops holding — which is correct for them and would be fatal here. A mention-ok counts as used when the code it names is cited within its scope, whatever the document’s state. Its claim is about the text, and the text does not change when the record does.

It still goes stale the one way that matters: when nothing in its scope cites the code at all, because then the mention it describes is gone. That is the signal worth keeping, and it is the only one that was ever about this annotation rather than about the document.

Alternatives

• Respell illustrative codes with the reserved FX prefix (ADR-093). The right answer when you control the spelling, and it stays the first choice. It fails when the spelling is the point: ADR-046 describes a bug about DP-17 being the code spelling a regex missed, and respelling it would falsify the thing being described.
• Exempt code spans and backticks from the reference scan. Rejected before and still rejected: the scan is unmasked on purpose, because a reference in a comment or a fenced block is still a claim about why the code is the way it is. “In backticks” is not the same as “makes no claim” — most backticked codes in this record are ordinary citations.
• Keep using unresolved-ok and absorb the churn. This is the status quo and its cost is now measured: every such acknowledgement is a scheduled failure, firing on the day someone allocates that number, at a moment unrelated to the work that trips it. DP-018 is one luria new dp away.
• Give the acknowledgement an expiry (until, ADR-095). Wrong axis. The problem is not that the claim ages; it is that the claim was about the wrong thing.

Consequences

A mention now has a word that stays true, so the annotation stops being a liability that fires on an unrelated event. The DP-018 failure does not happen, and the acknowledgements that survive a status change are the ones that were never about status.

The cost is a suppression that does not expire, which is the thing this record is most suspicious of. Two things hold it down. It is counted in the reports like every other acknowledgement — a suppression nobody counts is a suppression nobody notices — and it still reports as stale when nothing in scope cites the code. What it cannot do is tell you that a mention should have been a citation; that is a judgement, and this stays a report rather than a check.

FX remains the better tool where it applies. This is for the mentions whose spelling cannot move.