Config-first adoption: declared families replace defaults, and init scaffolds from a config

[dmarx]

Follow-up to #75, resolving the two limits it could only document — and answering the question that reframed them: can luria init not take a config file as input? It can now, and the two changes turned out to be one thought: luria.toml becomes the actual interface to what a record is.

ADR-047 — a declared family replaces the default; settings still merge

One merge rule produced both documented limits: the shipped ADR scheme couldn't be removed, and a declared scheme's omitted output inherited docs/decisions — silently relocating the index on the documented adoption path. A limit that well-documented is a bug with good paperwork.

The fix is noticing the config has two kinds of table:

• Settings tables (paths, code, lint, site) — keys named by Luria; partial override is the point → merge per key.
• Family tables (schemes, fragments, journals, remotes) — entries named by the project; declaring one is authorship → replaced whole when declared, shipped default when not.

Rejected: a removal sentinel (ADR = false is three states for a two-state question) and replace-on-any-write ([luria.site.theme.light] would clear the site table).

The two limit tests pinned in #75 fired the moment the rule changed — the only failures in the suite — and are flipped into their inversions. examples/rfcs-and-specs now has no ADR scheme at all; examples/collocated collocates by omission, workaround line retired; examples/many-journals shows an undeclared family surviving.

Upgrading: a config that declared part of a family while relying on the rest from the defaults now owns what it declared. Template-scaffolded records always declared families in full and are unaffected; the changelog says so.

ADR-048 — the scaffold is planned from configuration

luria init was a fixed-tree copy that ignored the one file that says what a record is — a project whose luria.toml declared RFCs and no decisions still got record/decisions.d scaffolded beside it.

Now: --config PATH → the project's own luria.toml → the template's, and the plan is a pure function of the winner. A directory, template and view stub per scheme; templates per journal and fragment dir; a docs index whose view list is generated from the config. ADR/DP keep the shipped rich templates (the doctrine is content Luria actually has); any other scheme gets a neutral template on the {PREFIX}-NNN placeholder luria new already substitutes — Luria has no opinion about what an RFC should say, and the template is honest about it.

The proven loop, now a CI-run test:

luria init --config team.toml   # RFCs + incident log, no decisions
luria new rfc
luria index && luria lint       # clean; no decision directory anywhere

One hard refusal: --config against a project that already has a luria.toml exits 1 — scaffolding one config's shape while another governs the record builds directories the project's machinery doesn't know about.

The guard caught two defects on its first run

Automating the adoption guide's three commands as a test immediately failed on a bare LU-ADR-048 I had just written into the template, and on a bare DP-1 sitting in the principles stub since before scheme-driven detection (#75) could see it. A fresh scaffold would have started red — the worst first lesson a reference-linting tool could teach. Both linked; the test stays as the pin for the class. Also fixed the sibling of #75's heading bug: an index scheme with no stub was titled # Architecture decision records whatever its prefix.

Verification

• 380 tests pass (369 at branch point): +5 merge-rule units, +5 init end-to-end, flipped pins, hardened adr_paths()
• All four init paths fired by hand before being pinned; luria lint clean, luria index --check current, luria site stages
• ADR-047 and ADR-048 filed Proposed; devlog carries the round, including the same-branch changelog-fragment collision after a squash merge (hand-named this round's fragment — worth a naming convention if branch-restarts become a habit)

---

Generated by Claude Code

[dmarx]

named for the branch

why are we naming changelogs fragments from the branch? this is a solved problem. use the timestamped filenaming scheme we're using for the devlog. it basically ensures fragments never collide. we should just derive changelog's similar to how we do with devlogs. also, I'm wondering if we should merge PRs into an intermediate branch without firing documentation builds on the PR, then we can build documentation on the intermediate branch. That way, every PR doesn't come up as changing 20 files, which is confusing in reviews.

[dmarx]

Both points addressed in aa23377.

Fragment naming — done as you describe. luria new now stamps an unnamed fragment with its filing moment (20260812-021035.md), the identity the devlog already uses. Flat rather than yyyy/mm/dd/ nested, because the collector and the lint glob a fragment directory one level deep. --name stays as the explicit override and still reopens rather than duplicates. One behavioral note: branch naming gave "second ask on this branch returns the same fragment" — timestamps can't, so two asks make two fragments, and they collect into the same dated batch anyway, which preserves ADR-002's reading intent via the collector instead of filename discipline. ADR-036 carries it as a version bump with history (the scaffold choice stands; only the naming detail moved).

The 20-files-in-review problem — I took the cheap swing first. .gitattributes now marks the generated views linguist-generated=true, which GitHub collapses in the Files tab by default (with a "load diff" click-through). A contribution's diff then reads as its sources, and nothing about the committed-views architecture changes — one file, reversible.

On the intermediate-branch idea itself: worth weighing if the collapse isn't relief enough, but it has real teeth. (1) The record a reviewer approves is no longer the record that lands — views regenerate after review, and the rendered index/summaries are sometimes where wording problems show. (2) luria lint's staleness guarantee currently assumes sources and views travel together in one tree; splitting them across branches means the lint passes on a branch whose views are supposed to be stale, so the check needs a mode. (3) Merge conflicts in generated files move from the contributor (who can regenerate) to the bot (which has to). If you want to go that way regardless — the collapse genuinely doesn't help git diff locally, only GitHub review — it's an ADR-sized decision and I'm happy to draft it with these trade-offs as the alternatives section.

---

Generated by Claude Code

[dmarx]

agree that it's an ADR-sized decision: I'm going to continue brainstorming outloud here. the issue is often conflicts over incremental codes taking the same the number across different branches. I'm wondering if maybe we should have a mechanism for issuing temporary codes, so within a branch the new docs can still be referenced by code, and then we can use a separate mechanism to concretize temporary codes into human-friendly incremental codes. so e.g. user wants to create a new document, so they run luria new adr and it generates record/decisions.d/adr-47fje0.md, so within the PR the user can sprinkle in references like [[adr-47fje0]]. in another PR, another user adds a fragment as well, [[adr-rn5gdh]]. they both merge together into the intermediate branch, no conflicts. Then the job that merges from the intermediate branch into main assigns them each real numbers, so adr-47fje0 becomes adr-123 and the other becomes adr-124, instead of them both claiming adr-123 and creating a conflict.

[dmarx]

This is the same move as the fragment fix, one level up: identity at filing time shouldn't require global coordination, and the sequence counter should live at the one place merges serialize. Filing-time numbering is a distributed claim on a global counter; that's the bug, and temp codes are the right shape of fix. A few things fall out of thinking it through:

The concretizer already has a name in the record. ADR-040 (Proposed) is "renaming schemes and moving documents without losing the record's memory" — and temp→real is exactly rename-plus-rewrite-every-reference, which luria link --fix and the wikilink machinery already know how to do inside the tree. Building concretization is building ADR-040's rename pass with a specific rename policy. One mechanism, two consumers, and the migration command stops being hypothetical.

The sharp edge is citations the rewriter can't reach. By the time adr-47fje0 becomes ADR-123, the temp code is in the PR thread, review comments, commit messages (immutable), maybe another repo's LU--prefixed reference. If concretization renames, all of those go dead. If it aliases — the new file keeps aka: adr-47fje0 in frontmatter and resolution honors aliases forever — then a temp code is never a dead reference, just an old name. That's consistent with ADR-013's whole argument (identity survives retitling because the code, not the title, is the address) and it keeps ADR-014's contract: no code that ever meant something resolves to nothing.

Temp codes don't actually need the intermediate branch. Concretization has to run wherever merges serialize — but a merge queue, or the merge-to-main job running it per-PR, serializes fine. The intermediate branch buys batching (and your docs-build point); the collision fix is orthogonal to it. Worth deciding them separately so the smaller mechanism isn't coupled to the bigger architecture question.

Mechanical touchpoints, for scoping: Scheme.number_of/documents() only match numeric filenames today, so temp docs would be invisible to the index and lint on the branch — the temp shape needs to be first-class there (indexed, linted, citable), with a distinguishable pattern (adr- + base36, say, never ambiguous with \d+). And main gets the inverse guard: a temp code on main is a lint failure — always wrong, mechanically fixable (run the concretizer), so it qualifies for the failing tier under ADR-035's own admission rule.

One genuine improvement hiding in it: the template says numbering carries information — the order decisions were made. Filing-time numbers actually lie about that under concurrency (branch A files first, merges second). Merge-time assignment makes the sequence mean what it already claims to mean.

When it pays: a single-human flow rarely collides, and today's collision is at least loud (add/add conflict on the same filename). N concurrent agent branches is where it becomes real — which I gather is exactly the workflow here.

Happy to draft this as a Proposed ADR — temp codes + alias-preserving concretization as the decision, with the intermediate branch, filing-time numbering, and timestamp-codes-forever (the devlog answer, which trades away small citable numbers) as the alternatives section. Say the word and it lands as its own PR.

---

Generated by Claude Code

[dmarx]

draft this as a proposed ADR, file the proposal with this branch, merge this change, start a new PR on a new branch implementing the proposal.