Segregate Luria's own project memory into meta/

[dmarx]

Addresses #3. Recorded as ADR-021.

The shape

docs/         what the package documents — doctrine, directives, adopting
template/     what `luria init` writes into a project
meta/         Luria's own record: decisions, principles, devlog
luria/        the tool

docs/ is four pages now. meta/ says in its own README that it is evidence, for contributors, and that nothing in it ships.

Why this shape

Measuring first changed what the fix should be. The scaffold luria init writes is 16 files / 28.6 KB; the record was ~300 KB. So under pip install && luria init the deadweight the issue describes is already zero — nothing in the record was ever inside template/. What was actually wrong is that a visitor opening docs/ met twenty decisions about Luria's internals before reaching the four pages that are the product. A navigation problem wearing a token-cost costume, and a directory rename fixes it.

Rejected: a separate repo, submoduled. It costs the property that makes the package credible — ADR-009 is a claim that has to keep being true, and several tests are deliberately corpus-dependent against this corpus. Move it out and luria lint here has nothing real to lint. It also doesn't solve the stated problem: --recursive is standard enough that the bytes come along anyway.

Rejected: inverting the layout to hoist template/ to the root. Same outcome, much larger diff, and the root would then mix the scaffold's files with the package's.

Config

paths.docs accepts a list of roots, each indexed by its own README:

[luria.paths]
docs = ["docs", "meta"]
decisions = "meta/decisions"

Per root rather than repo-wide — one index spanning both would put each audience's material in the other's way, which is the thing the split fixes. The plain string form is unchanged and stays the default, so template/luria.toml needs no edit and a scaffolded project gets no meta/.

Two hardcoded paths, both of which would have failed open

• badges.region() defaulted its link to the literal "docs/decisions/README.md" — a default restating a configured value. After the move both README badges pointed at nothing. It reads current().index now.
• The reference lint reached the decisions only because docs/decisions/ sat under cfg.docs. A scheme directory is now scanned on its own account, so meta/decisions/ can't silently drop out of the hyperlink lint — which is exactly the fail-stale polarity DP-3 rules out.
• A journal's source directory joins the index check's exemption list, like a scheme's. It only became visible to that check by moving inside a documentation root.

What didn't need touching

Every link inside the record survived. The whole thing moved together, so ../design-principles.md#dp-3 from an ADR still resolves — docs/decisions → docs/ and meta/decisions → meta/ are the same two hops. Only the 94 links crossing the boundary were rewritten, plus one from README.stub back out to the doctrine. The journal entries needed nothing at all: link_base resolves them from the journal's configured output directory, so changing one line of luria.toml moved all of their link bases at once.

Assumption worth overruling if wrong

CHANGELOG.md and changelog.d/ stay at the repository root. The asymmetry with the devlog is deliberate: a changelog is a claim about the package, which an adopter reads, and a root CHANGELOG.md is a universal convention; the devlog is how the package came to be, which only a contributor reads. Sorting by audience puts them in different places even though they look like siblings. Easy to move if you'd rather they travel together.

Verification

• luria lint clean; 191 tests pass (6 new covering multi-root indexing and scheme scanning).
• Both new guards fired deliberately (DP-6): an unindexed page dropped into meta/, and a bare reference added under meta/decisions/. Each produced exactly one violation naming the file.
• 600 relative links re-resolved from their render bases, 1 "broken" — the ADR-NNN.md placeholder in the decision template.
• Fresh scaffold end to end into an empty directory: luria init → index → journal new → index → lint, clean, and the result contains no meta/.

Still open on #3

The distribution mechanism itself (PyPI, a release tarball of template/, or both), and the bare local codes in template/ — template/luria.toml cites (ADR-005), (ADR-012), (ADR-020) and template/changelog.d/_template.md cites (ADR-002), which will resolve to an adopting project's decisions rather than to Luria's. Neither is blocked by this change. Happy to take the second one next as a small follow-up with a lint rule.

---

Generated by Claude Code

[dmarx]

This was a fruitful exercise and I'm glad we proved out that refactoring the project structure like this was fairly painless. I think maybe I was thinking about it wrong and so I'm going to just think outloud for a moment to try to better characterize what's bugging me about the current layout. hopefully that will help pin down what problem this PR should be solving and we can then better tailor our intervention.

The themes that are popping up in my head right now are discoverability, attention engineering, overwhelm, and hot/cold storage. When I proposed that PR earlier, I had frankly completely forgotten that we were already designing around a template + init command.

We've already identified that we want to make it clear where the borders are between the downstream deliverable and the scaffolding which supports it. I think maybe where we still don't have well defined boundaries is between the atomic ground truth artifacts and the generated views. changelog.d and devlog.d are both top level directories, exposed as siblings of CHANGELOG.md and docs/. that's two of the three fragments directories exposed as if they're normal user facing locations. the other fragment directories are tucked away in docs/principles/ and docs/decisions, with no .d designating them as fragment containers. Then again, the generated docs/design-principles.md is a sibling of the fragments container it's generated from, docs/principles/. The generated entrypoint to the decisions is docs/decisions/README.md, which looks like it should make sense, except that file is a direct sibling of the fragments it's generated from which all sort on top of it because of the ADR- prefix, so the generated document is completely buried, and also sits right next to its .stub which I think is a strong indicator that it belongs somewhere else. The generated entrypoint to the logbooks is buried all the way at docs/devlog/README.md, with the current devlog at docs/devlog/2026-08.md, which makes it look like an archival journal rather than an intended reading target for the user.

I think what's bugging me is less about meta separation than it is about our current structure broadly. We should make it clearer what the user should be reading vs where the user should be writing. There are certain documents we want to draw the user's attention to because they are entrypoints or summaries: we should make sure these artifacts are front-and-center. We should make it easier to land on the read content accidental and harder to land on the write content accidentally.

Closing in favor of an exercise which better addresses these presentation issues.