jschoubben
a2495e4d8e
how-we-build 5 already says that if a document states a rule about the mesh, it says how the rule is verified — an unenforced rule being indistinguishable from a wrong one, and costing more because people believe it. That has never been applied to decisions, and a decision record states the same kind of claim. The gap was found by review: the lab reached 2,128 lines with 1,072 untested and no stated rule broken, because there is no testing posture in how-we-build at all. Every decision the lab embodies was verified by hand and none of it survives the terminal it ran in — which is 04-ISSUES/005 in miniature, coverage assumed rather than checked. Rejected a coverage percentage: it measures how much code a test touched, not whether anything important is defended, and would have been satisfied by testing the parser harder while the hypervisor integration stayed unasserted. Rejected test-driven development as a hard rule, and not because it is wrong in general. Half this implementation was discovery — that the hypervisor CLI reads a definition from stdin and hangs, that it assigns a MAC without recording it, that a stock image's networking flushes a static address. A test written first against undiscovered behaviour asserts a guess. So: structure and logic tested first, behaviour against a real system tested alongside, mocking the boundary forbidden, and a blocking gate as the definition of done. A test names the decision it defends, which is what makes the pairing checkable — a decision without one can be found rather than noticed. Stated as proposed rather than adopted: 6 requires review by someone who is not the proposer. Records 0001-0033 predate it and are not retroactively invalid, but each should acquire a test or an explicit note that it cannot have one, and until then the rule is aspirational for them — which is the state 5 warns about, recorded rather than hidden.
00-META
The northern star. What the mesh is, the environment it runs in, and what changes when it works — plus the engineering practice that holds across everything Novox builds. Every research effort and design decision is checked against this folder.
| File / folder | Purpose |
|---|---|
mission.md |
Vision, mission, and the values that decide arguments |
context.md |
The environment — conditions, not aspirations |
effect.md |
What is different when the work is done |
how-we-build.md |
The rules that hold across the mesh, each one earned. The source of the mesh constitution — the governed page the mesh injects into design sessions is derived from it. |
repos.md |
Where implementation lives, and what each repository owns |
process/ |
The playbooks — how work moves through this repository, for engineers and agents alike |
Rules
- Markdown only.
- Stable by nature. Changes here reflect a genuine shift in intent, not iteration. The one
exception is
how-we-build.md, which changes whenever a rule is earned — and only through its amendment process. - Research and design must be traceable back to what is written here.
- Instance-agnostic. These documents describe the mesh as a concept. No machine names, no counts, no topology.
On the architecture overview in the code repository
The code repository carries an architecture overview predating this folder. It is a useful
description of how the mesh works, and its content now lives — anonymised and checked against
the implementation — in 03-DESIGN/00-as-is/. GENESIS answers why;
that document answered how, which is the design layer's job.
It had also drifted from the implementation in ways worth recording, since both were found by comparing it against the code rather than by anyone noticing:
- It described the pipeline as having a separate builder process and a build stage that packages. Neither was true after 2026-08-04; the documents stayed stale until 2026-08-06 (ADR 0014).
- It listed the mesh as spanning a fixed number of named machines, which is exactly the content this repository cannot carry.
It also lists "symlinks, not copies" as a key design principle, and that is a genuine contradiction rather than a stale detail. The mesh's stated intent is that it creates no symlinks at all — the rule is not merely "only the installer may link", and a founding document elevating linking to a principle points the opposite way from where this is going.
What exists today is that the installer owns and reconciles every link
(ADR 0011) — an as-is fact, recorded in
03-DESIGN/00-as-is/05-runtime-and-installation.md.
Centralising who may link narrowed the incident class; it did not close it. The intent is to
remove the mechanism, recorded as ADR 0018.
A founding document contradicting the direction of travel is precisely the failure this folder exists to prevent.