luria

Document status is reported, not enforced

4 min read

Graph View

ADR-007: Document status is reported, not enforced

Status Superseded — by ADR-035 · Version 2 · Filed 2026-08-03 · Influenced ADR-022 · DP-006

Context

ADR-003 made status sayable and ADR-004 made it visible on one page. Neither reads it in context, and context is where the field earns its keep. A Deferred decision cited from live code reads as the settled reason the code is shaped that way. A Proposed one cited as settled architecture is the same class of drift the status field itself had — except nothing was looking.

In the project this was extracted from, the first run found ten retired decisions cited from current docs and code, one of them Deferred and cited thirty-seven times including from shipped source. And nine decisions were Proposed or Deferred with nothing anywhere recording for how long.

Decision

Two standing reports, both warnings, neither able to fail a build.

  1. Reference status — unacknowledged references to retired documents, grouped, most-cited first, with sites.
  2. Pending decisions — undecided decisions oldest first, with age and citation count. Age alone is a list; age plus citations is a priority order. An old proposal nothing cites is a stalled idea worth closing; an old proposal thirty-seven files cite is a decision already made and never written down.
  3. luria reports writes both as markdown for a CI artifact. Console summaries carry no file or line, and detail behind a command nobody runs is detail nobody reads. (v1 also shipped each report as its own command — that proved the point rather than the mechanism, and ADR-030 retired them.)

Warnings, not errors, on purpose. Citing a Rejected decision is often exactly right — it exists to be pointed at — and a decision can be legitimately open for months. A guard that is wrong most of the time gets suppressed, and then the times it is right go unread too.

To keep the reports converging on what nobody has considered, a deliberate reference is acknowledged in a comment:

<!-- inactive-ok: ADR-012 — the decision this replaced -->

Acknowledgements are counted in the report rather than hidden, and one that stops applying — the document went Active, the reference was deleted — is reported in its own right. A suppression that rots silently is the failure the whole ADR is about.

The two reports count different things and their numbers legitimately differ: reference status covers documents something cites and hasn’t acknowledged; pending covers every undecided decision. Both headlines say so, because side by side they read as an off-by-one.

Alternatives considered

  • Make it a lint error. It would fail CI on citations that are correct — a decision legitimately cites the one it superseded. Contrast ADR-005, where the violation is always wrong and mechanically fixable, which is what makes failing right there.
  • A ratchet: fail when the count rises. Genuinely tempting. Rejected for now because the baseline would be a checked-in number every decision-bearing contribution touches — the lock DP-2 names, and the exact thing ADR-004 removed from this directory. Worth revisiting if the reports get ignored.
  • A bot that flips stale Proposed to Rejected. Rejected outright: it invents a decision nobody made, and the record would then lie with authority.
  • A review-by: date in frontmatter. A second hand-maintained field, free to drift from the first, when date: plus the clock already answers it.

Consequences

  • Exit codes are unchanged, so nothing starts failing on a correct citation.
  • Every CI run leaves the full detail as an artifact, diffable across runs — which is what turns a standing warning into a signal.
  • A warning nothing fails on needs its tests more than a lint does: when it silently starts reporting everything or nothing, no build goes red to say so.

Backlinks