ADR 0001 — atlas: a cross-repo structure layer, orthogonal to design

Status: accepted
Date: 2026-06-02

Context

The Bitspark constellation is many repos: the substance stack (ontos → logos → arche), members being placed (stele, thesmos), and the design infrastructure repo. design already proved the value of a plain-named, orthogonal repo that owns one cross-cutting concern (the visual language) and ships tooling to enforce it.

But a second class of cross-cutting concern had no owner, and it kept drifting:

Topology — how the systems relate — lived in design/styleguide/family.md, i.e. filed under look & read though it is really build & relate.
Cross-repo diagrams — a figure depicting >1 system — had nowhere to live; design/figures.md says each figure is owned by the repo it depicts, which leaves inter-system diagrams homeless.
The dev-workflow scaffold (worktree scripts, CLAUDE.md/AGENTS.md) was hand-copied into every repo and silently diverged.
Cross-cutting invariants (acyclic dependencies, every README links its named siblings) were noted in prose but enforced nowhere.

Decision

Create atlas: a plain-named, orthogonal infrastructure repo that owns the constellation's structure, as design owns its surface.

Membership test. A thing belongs in atlas iff it (a) concerns ≥2 systems or the whole, and (b) has no natural single-repo owner.
Boundary. look & read → design; build & relate → atlas. atlas consumes design (diagrams are drawn in design's figure language, linted by design).
Source of truth. topology/constellation.json is machine-readable; family.md is generated from it. Invariants are enforced by the zero-dependency atlas CLI (doctor, topology gen --check, crosslinks), which ships centrally and runs in every repo's CI — because copies rot silently.

Consequences

family.md migrates out of design to atlas/topology/ (a follow-up touching design); design keeps only the visual language.
New systems are registered in constellation.json; their place can be marked draft until ratified (stele and thesmos are draft today, pending their edges).
atlas dogfoods its own workflow scaffold, which other repos then vendor.