ADR, OpenSpec, and the lattice (lat.md/): a change-machine, a decision log, and the substrate that holds the vocabulary, both of them quietly assume.
The Decision That Was Never Written Down
Eleven months ago someone on your team decided that a tenant boundary lives at the Account model, not the Workspace model. There was a reason. There was probably a Slack thread. There may even have been a diagram on a whiteboard that got wiped the next morning.
Today an agent — or a new hire, the failure mode is identical — reaches the same area of the code, sees a Workspace model sitting right there, and routes the new feature through it. Nothing breaks in CI. The diff is plausible. The PR merges. Six weeks later an integration test in staging reveals that you now have two contradictory notions of “tenant” living in the same codebase, and nobody can point to the moment the rift opened.
The code remembers everything. The why evaporated the moment the whiteboard got wiped.
If you have lived this, you already know the standard answers, and you already know they only half-work.
The Two Half-Answers Most Teams Already Have
Answer one: write it as an ADR. Architecture Decision Records are the right instinct. An ADR is immutable, dated, and names the forces behind a decision. Michael Nygard’s 2011 essay is one of the highest-leverage half-pages in software engineering. If the Account-not-Workspace decision had been an ADR, the agent that contradicted it eleven months later would have had something to honor.
But ADRs have a structural limit: they record individual decisions, in a flat, append-only log. Past about your tenth ADR, the log loses its shape. ADR-0042 silently contradicts ADR-0003 and nobody notices, because nothing connects them. An ADR knows what was decided. It does not know what other decisions it touches, what vocabulary it assumes, or what invariant it quietly depends on.
Answer two: drive changes through a spec. OpenSpec — the lightweight, brownfield-first member of the spec-driven-development family — fixes the flow. You propose a change as a self-contained folder (proposal.md, design.md, tasks.md, a spec delta), you validate it, and on archive the delta folds into a living spec under openspec/specs/. The living spec is what is; the change folder is what should be. It is a clean, boring, durable convention, and it is the backbone of the pipeline I wrote a book around.
But OpenSpec specs have a complementary limit: they describe what each capability does, capability by capability. The spec for checkout knows about checkout. The spec for billing knows about billing. Neither one holds the thing that spans both — the canonical definition of Order, the invariant that totals are never negative, the saga pattern you committed to once and now assume everywhere.
So you have a decision log that records points without edges, and a spec set that records capabilities without the connective tissue between them. The thing that sits between a capability and a decision — the vocabulary, the invariants, the patterns, the load-bearing concepts that cut across every change — has no home. It is being held in someone’s head. Usually the head of the person about to leave.
The Missing Artifact: The Lattice
The fix is a third durable artifact that sits beside the other two and holds exactly what they drop. I call it the lattice, and it lives on disk as lat.md/ — a sibling of openspec/ at the repo root.
The name is a structural claim, not decoration. A lattice in mathematics is a partially ordered set where the relationships between elements are first-class. Formal Concept Analysis (Wille, 1982) borrowed the construct for knowledge representation: nodes are concepts, edges are containment. The forge’s lattice is the same idea with one concession — we don’t insist on a fully formal order. We insist only that every node is identified, every edge is named, and every claim is grounded in a node somewhere.
It holds five node types:
Node typeWhat it capturesADRA durable architectural decision (the MADR-short ADR you already know)VocabularyThe canonical definition of a domain term — “Order: a finalized basket with a non-mutable line-item list”InvariantA property that holds across capabilities — “totals are non-negative integers in the smallest currency unit”PatternAn accepted pattern and the contexts where it applies — “saga for cross-aggregate consistency in checkout”PrincipleA rule of thumb that constrains future decisions — “prefer cheaper falsifiability rungs: type before property before prose”
The ADR is the node type you already write. The other four are the parts the existing setup had no place for. arc42’s chapter 8 (”Cross-cutting Concepts”) is the closest prior art; the lattice gives that idea cross-link discipline and makes it machine-checkable.
The edges are the whole point. Five named predicates — supersedes, implies, constrains, defines, honors — and nothing else. A flat ADR log can’t say this pattern honors that ADR or this invariant is implied by that decision. The lattice can, and that is the difference between a pile of records and a navigable map.
Why The Three Compose Instead of Compete
This is the part that took me a while to see clearly, so let me state it plainly.
OpenSpec is the assembly line. The lattice is the warehouse. ADRs are one shelf in that warehouse.
A change moves down the assembly line: proposed, grilled, reconciled, emitted, dispatched, verified, archived. Almost everything it produces is ephemeral — proposals get archived, designs get filed beside their change, tasks get checked off. But every change also draws from and replenishes the warehouse. It honors invariants that already exist. It uses vocabulary that’s already defined. And occasionally it mints something new and durable — a fresh ADR, a new term, a newly-load-bearing invariant — which gets promoted into the lattice on archive.
The keystone move is what happens at the bottom of every design.md: a structured Lattice Footprint section the architect writes during emission and the archive step parses.
## Lattice Footprint
### Honors (existing nodes this change depends on)
- lat:adr/0001-postgres-for-catalog
- lat:invariant/totals-non-negative
- lat:vocab/order
### Mints (new nodes this change introduces)
- lat:adr/0079-passkey-only-public-auth
supersedes: lat:adr/0002-oauth-only-for-public-api
- lat:vocab/passkey-credential
### Touches (existing nodes whose Consequences this change updates)
- lat:pattern/oauth-public-api
status: deprecated by lat:adr/0079On openspec archive, three operations run in order: mint the new nodes, touch the affected ones (append to their Consequences trail, never edit their frozen bodies), and resolve every lat: reference so a dangling link aborts the archive. Validate is permissive; archive is strict — the same asymmetry OpenSpec already uses for spec deltas, now applied to the knowledge substrate.
That single coupling point is why the three artifacts reinforce each other instead of fighting:
ADRs get a graph. Instead of a flat log where ADR-0042 silently contradicts ADR-0003, every ADR is a node with named edges. Supersession is traversable. The contradiction the agent would have introduced eleven months later now fails a lint.
OpenSpec gets a memory. The living spec stops being a set of disconnected capability descriptions. Every
THENclause either honors an existing invariant node or mints a new one. The vocabulary you say in the interview is the vocabulary already in the lattice — so when you say “basket” and the lattice haslat:vocab/order, the architect catches it on the first draft.The lattice gets fed automatically. It isn’t a wiki someone has to remember to update. It’s replenished by the archive step of a pipeline your team already runs. The substrate maintains itself as a side effect of shipping changes.
The Durability Ladder
Here’s the frame that makes the whole thing click. Every commitment your system makes can be captured at one of four rungs, and you want the cheapest rung that holds:
- 1.
Prose — the narrative in
proposal.mdanddesign.md. Useful for humans, useless to machines, re-interpreted on every read. - 2.
Property — an executable invariant (the kind that compiles to
fast-checkorproptest). Stable across model upgrades. - 3.
Lattice node — the durable cross-cutting fact. More durable than a property because it constrains every future change, not just the current one.
- 4.
Type — the compiler-discharged fact. A
u64that can never be negative. Cheapest of all.
Pick the lowest rung that captures the invariant. A type beats a property beats a lattice node beats prose. But not every commitment fits the type system, and not every commitment fits a property suite. The lattice is the rung that catches what the other three drop — the vocabulary, the architecture, the principles that no language and no test framework knows how to hold.
The Anti-Patterns That Eat Lattices
Three of the six failure modes I watch for, because they’re the ones that look like good practice:
“We’ll keep the lattice in our heads for now.” This is how every team starts. It is also why every team’s twelfth ADR contradicts its third without anyone noticing. The substrate exists either as a directory you can grep or as a fragile shared mental model. There is no third option.
The vocabulary node that drifts from the code. lat:vocab/order says “a finalized basket”; the Order type accepts mutations. The fix is never to edit the node — it’s a verify-stage escalation that supersedes the node when reality changed, preserving the audit trail of when and why.
The principle that is actually a preference. lat:principle/no-singletons reads like a rule, but it names no failure mode it prevents. A principle without a named failure mode is a preference. Move it to a style guide; keep it out of the lattice.
The discipline that makes ADRs trustworthy — append-only, supersede-don’t-edit, grill-before-you-freeze — is the discipline that makes the whole lattice trustworthy. Nothing less will do.
The Smallest Possible Pitch
Your repo already remembers the code. Git guarantees it. What it forgets is the why — and the standard answers each fix half the problem. ADRs record decisions but lose their shape past ten of them. OpenSpec records capabilities but drops the connective tissue between them. The lattice is the third artifact: the durable substrate that holds the vocabulary, invariants, patterns, and principles both of the others quietly assume — fed automatically by the archive step of a pipeline you already run.
Specs are the proximal projection of the lattice onto the current capability set. Code is the side effect of the projection. The lattice is the warehouse the whole assembly line draws from, and, on every archive, replenishes.
The Book
I wrote The Clarity Forge to lay out the full pipeline — the OpenSpec setup, the copy-paste glue prompts that connect each stage, the ADR grill that interrogates decisions before they freeze, the property compilation that makes specs falsifiable, and the bonus chapter that introduces the lattice as a first-class artifact with its directory layout, cross-link protocol, archive integration, and the tooling you actually have to build (under 300 lines: lat lint, lat index, lat graph).
It is a mini-book. A weekend read. A Monday-morning toolkit. It is the companion to the longer The Clarity Engineer: Code Is the Side Effect, which names the underlying discipline.
If your repo remembers the code and forgets the why, the book is for you.
📖 The Clarity Forge — on Leanpub.
https://leanpub.com/clarityforge
📖 The Clarity Engineer — on Leanpub
https://leanpub.com/clarityengineer
and Amazon.
Stop vibe-coding. Start building a substrate that remembers.
Volodymyr Pavlyshyn writes and builds at the intersection of agent orchestration, AI engineering discipline, and the durable artifacts that make software teams legible to themselves.
Originally published on Sovereign Agentic AI on Substack.