Context
SHAPED_RE matches a directive from its name up to the em-dash, and
shaped_spans blanks exactly that run before the reference scan runs. The
argument list is syntax — naming a code in a directive is governing it, not
citing it — and everything after the em-dash is ordinary text, scanned like any
other prose.
That boundary is not obvious from the outside, and it has now produced the same bug twice in one week, both times in an acknowledgement I was editing to fix an acknowledgement. Rewriting a reason, I named the governed code in the explanation: “the DP pair became visible…” became “DP-018 became visible…”. The argument list was blanked, the sentence was not, and the annotation acquired a citation that it then excused. The mention existed only because the annotation explained itself.
The second time was worse in a specific way: the cost-reporting check reported that self-made citation as a site the annotation was covering, and I read the number as evidence the acknowledgement was earning its place.
There is a further wrinkle. In the first case the code was on a continuation comment line, which is not part of the directive’s matched span at all — it is a separate comment fragment. So “blank the reason too” would not even have caught it.
Decision
The boundary stays where it is: the argument list is syntax, the reason is prose, and a code named in a reason is a citation like any other.
The rule that follows is the one this exists to write down: do not name a governed code in an acknowledgement’s reason. The argument list is where a code is governed; say “the DP code here” and the sentence reads the same without creating the citation it is excusing.
Alternatives
- Blank the whole comment the directive introduces. The obvious fix, and
the one the working agreement points at — a hazard that catches you twice is
a bug report about the workflow. Rejected on two counts. It would swallow
genuine citations: an author writing “superseded by ADR-060” in a reason
means that reference, and the reference graph should have it. And “the whole
comment” is not a fact the parser has — a block’s end is what
blocks()guesses at and whatsyntax.growexists to correct, so this would build a silencer on top of a guess and silence most reliably where the guess is worst. - Blank the reason but not continuation lines. Cheaper and wrong: it fixes the case the parser can see and leaves the case that actually bit first, which was a continuation line. A fix that covers the easier half of a hazard is worse than none, because it retires the vigilance without retiring the hazard.
- Leave it unwritten and rely on care. The status quo, and its record is two for two against a reader who had just finished debugging this exact mechanism.
Consequences
The rule is cheap to follow and costs a reader nothing. What it does not do is catch you: nothing reports a reason that names its own governed code, so this is a thing to know rather than a thing that is checked.
That is the follow-up this implies. The violation looks mechanically detectable — a governed code appearing inside its own directive’s comment can only produce a self-excused citation, which is never informative — and if that holds it belongs in the report alongside the other annotation findings. It is not built here, because the same continuation-line problem that defeats the blanking fix has to be solved to find the text in the first place, and that deserves its own look rather than riding along with the decision.