A document can opt out of reference checking, and the report counts it

ADR-033: A document can opt out of reference checking, and the report counts it

Status Active · Filed 2026-08-07 · Issue #37

Context

The directive vocabulary is code-scoped: inactive-ok, unresolved-ok and url-ok each excuse one code, and the -file suffix only widens where the excuse applies, never what it excuses. The only whole-file mechanisms were config-level and partial — [luria.code] historical skips the scan but not the link lint, is_generated skips everything but only for view directories the generator owns.

So a fixture-heavy page or a vendored document needed one directive per code, maintained forever, and the ADR-032 work had nothing lighter than is_generated to reach for when the reports directory needed excluding (#37).

Decision

<!-- unlinted-file: — reason --> exempts the document from the reference machinery: the bare-reference lint, wikilink handling, and the reference-status scan. One choke point per exit — rewritable_refs and wikilinks return empty (so the lint and the fixer cannot disagree, the ADR-005 property), and the scan skips the file.

File scope only. A narrower “don’t read references here” already exists — that is what quoting a code in backticks does — so unlinted: and unlinted-block: govern nothing, and are reported as misuse rather than silently ignored (DP-1).

Counted, never hidden. Opted-out files are collected by the scan and listed in the reference-status report, with a one-line count in the lint’s warnings. The ADR-007 bargain: acknowledgements are visible so the reports converge on what nobody has considered — and a whole-file exemption is the one suppression they cannot converge past, so its visibility is the price of its bluntness.

Reference checking only. Frontmatter, titles, the staleness gate and a journal’s path checks still apply. The directive exempts the references, not the document.

Alternatives considered

• A config file-list ([luria.lint] skip = [...]). Rejected: every other excuse in the vocabulary lives where the reference is, carrying its reason in the same comment — a list in luria.toml divorces the exemption from the page it governs and from any explanation.
• Support line/block scopes. The uniform scope rule argues for it, but the narrow form already exists as backticks (a quoted code is a specimen), and a second spelling for the same exemption is a projection to keep aligned. Misuse reports the remedy instead.
• Exempt everything, not just references. A page opted out of frontmatter and staleness checks is a page the machinery no longer knows about at all; the observed need was only ever about reference noise.
• Status quo — one directive per code. Works, and is right for pages with one or two specimens; the reference report keeps recommending it. This directive is for the page where the per-code ledger is longer than the content.

Consequences

• The reference-status report gains a standing section — “Files that opt out of reference checking” — that says ✅ when empty, so the account stays complete either way.
• An unlinted-file: page’s own inactive-ok/unresolved-ok annotations stop being collected, which is coherent (nothing is scanned that they could excuse) but worth knowing before combining them.
• docs/directives.md documents it; the “Adding a fifth directive” recipe proved accurate and now reads “sixth”.