luria

Reference schemes and paths are configuration, not constants

3 min read

Graph View

ADR-006: Reference schemes and paths are configuration, not constants

Status Active · Filed 2026-08-03 · Influenced ADR-044 · ADR-045 · ADR-046 · ADR-047 · DP-004

Context

This machinery was built inside one project, where every path was a constant: the issue URL, the decisions directory, the globs naming which source files to scan, the two files that are dated records rather than current guidance. All correct, all specific, and all in the way of using it anywhere else.

The subtler version of the same problem is the vocabulary. The annotation that acknowledges a deliberate reference could have been adr-ok: 012 — shorter, and correct for exactly as long as ADRs are the only referable documents.

Decision

One config file, luria.toml, and a scheme registry.

[luria.schemes.ADR]
dir = "docs/decisions"
active = "Active"

A scheme is a prefix, a directory, and the status that means “in force”. Its documents need frontmatter with a status: and nothing else. Adding an RFC directory or a spec index is an entry here, not a fork of the scanner.

The vocabulary follows from that: inactive-ok, not adr-ok, and a code carries its prefix. ADR-012, never 012 — a bare number is reported as a malformed annotation rather than assumed to be an ADR. That is what lets one annotation syntax serve more than one scheme.

Everything else specific to a project lives in the same file: issue_url, the docs paths, the fragment directories and what each collects into, the code globs to scan, and which files are dated records. Every key has a default, so a conventional project needs only issue_url — and Luria runs with no config at all, which is what lets luria init bootstrap.

Alternatives considered

  • Arguments threaded through every entry point. Works until the second caller forgets one and the linter and the fixer cover different files — the exact failure DP-4 and ADR-005 exist to prevent.
  • adr-ok: with bare numbers. Shorter to type, and a rename across every annotation in every adopting project the day a second scheme appears.
  • Convention over configuration — fixed paths, no config file. Tempting, and it fails on the first project that keeps decisions somewhere else, which is most of them. Defaults give the convention; the file gives the escape.
  • Auto-detect schemes by scanning for XXX-NNN.md files. Clever, and it would silently promote an unrelated filename pattern into a reference scheme.

Consequences

  • One module knows a particular project; the rest are generic.
  • A second scheme is a config entry plus a directory of documents.
  • The config is read once per process and cached, so the file’s mtime can’t become a source of skew mid-run.

Backlinks