jschoubben
333356cff3
Jochen asked whether the order made sense. It did not -- it followed when things happened to be decided, which after consolidation is fictional anyway since record 5 alone folds decisions taken across a week. Concretely wrong before: the domain statement sat at 8, after five engineering rules; the constitution was scattered across 5, 12 and 17; the tiers landed at 15, 16, 21 and 22 with process records in between. Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what runs on them and how it gets there (9-10), how it is built (11-16), how it is checked (17-18), how we work (19-23). Two things made this safe rather than free. It is a permutation, not a compaction, so the renames go through temporary names -- otherwise two files want one slot and one is lost. And the reference rewrite is a single simultaneous pass, because almost every number moved into a slot another number was vacating; replacing one at a time would have cascaded and pointed things at the wrong record while still resolving. Verified: 284 [ADR NNNN](path) links across the repository, all with matching text and target. The ordering principle is now stated in 19 rather than left implicit -- the repository already said "the numbering is the flow" about its folders, and there was no reason for the records to be the exception.
5.7 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-08-28 | jochen | false |
19. How this repository works
Consolidated 2026-08-28 from ten records that were one decision seen from ten angles. The reasoning is kept; the fragmentation is not.
The repository
novox/hq is Novox's headquarters, and it is public.
Company-scoped, not the mesh's. Today almost everything in it is about the mesh, because the mesh is what Novox is building — a fact about the present rather than a definition. A second product would live here too.
Public means written for a reader who is not its author and has no access to the mesh it describes. Nothing here may contain routable addresses, real domain names, node names, absolute paths, usernames or credentials. The test: would this paragraph still teach a stranger running an entirely different mesh?
Separate from the code because the cadence differs — a decision changes when thinking changes, not when code changes — and because a public repository cannot be a private one's subdirectory.
The naming rule: a repository belonging to a product carries that product's prefix. A
company-scoped one does not. So this is hq and the mesh's are mesh-*.
| Repository | Tier | Holds |
|---|---|---|
novox/mesh-host |
0 | the node host — the one binary installed by hand |
novox/mesh-substrate |
1 | the pinned tier-1 services, as declarations |
novox/mesh-control |
2 | the control plane and its contexts |
novox/mesh-surfaces |
3 | tools, web, cli — thin, no logic |
novox/mesh-sdk |
— | the mesh's own domain (ADR 0009) |
novox/mesh-lab |
— | the lab: scenario lifecycle, networking, placement |
novox/hq |
— | this one |
The product is Novox Mesh, shortened to mesh in internal use — repository names, the
module namespace, environment variables, paths. Nox is an identity of Novox, an agent
participant within the mesh's own model, not a second system.
The folders, and why they are numbered
The numbering is the flow. Research produces a decision; the decision authorises a design. Following the numbers walks the process in the order it happens.
01-RESEARCH |
an open question, while it is open |
02-DECISIONS |
what was decided, and why |
03-DESIGN |
what is being built |
04-ISSUES |
something wrong at the level of design or governance |
03-DESIGN has two layers and they are never mixed. 00-as-is/ describes the mesh that
exists, written from the implementation and the operational record. 01-to-be/ describes the one
being built toward. Every document says which it is. A statement about the future does not belong
in an as-is document, and an as-is document is never edited to describe an intention.
04-ISSUES is for design-level faults — a rule enforced by nothing, a stated invariant that
is false, a failure the design permits to be silent. Not an operational ticket queue.
What a decision record is, and is not
If a decision is worth recording, it is worth a record. If it is not worth a record, it is not recorded.
That bar has been read too generously. A finding is not a decision. A bug is not a decision. A record is warranted when there is a genuine fork: a direction reversed, an alternative seriously considered and likely to be proposed again, or something contested that needs to stay settled. Everything else belongs in the design document, where the reasoning is read.
There is no ledger — no separate document summarising, ranking or tracking decisions. A chronological view is generated from frontmatter, which is what a ledger was actually for.
The numbering is the flow here too. Records are ordered the way somebody would learn the system — what the mesh is, then its tiers from the bottom up, then what runs on them and how it gets there, then how it is built, how it is checked, and how we work. Not chronologically: the date is in the frontmatter and a consolidated record holds decisions taken across a week, so ordering by age would order by an accident that no longer exists.
The design layer is what you read. These records explain why a thing is as it is. They are not a description of the system, and needing to read them to understand it would mean the design documents had failed.
Status, and views over it
Every document carries its state in YAML frontmatter — research overviews, design documents, decision records, issue reports.
There are no central status files. Every cross-cutting view — a status matrix, a decision index, an open-issue list — is generated from frontmatter when asked for, never written to disk. Two places holding one fact drift, and the written one wins by being closer to hand.
Prose does not restate status. One place, and two is one too many.
Workflows are playbooks
Every workflow is a playbook in 00-META/process/: trigger, who runs it,
steps, outputs. People and agents follow the same ones, and agents do not act outside them.
Each is wrapped by a thin skill that defers to the playbook as authoritative and adds only the mechanical scaffolding — so the process has one definition rather than a document and an implementation that disagree.
Consequences
- A reader has one place per thing. The design layer describes the system; these records say why; the playbooks say how work is done.
- Records will accumulate more slowly, because the bar is a fork rather than a finding. This record is itself the correction: ten records became one because they were one decision.
- The public rule constrains everything written here, permanently and at every commit. It is the reason research describes real observations without identifying the mesh it observed.