140 lines
7.2 KiB
Markdown
140 lines
7.2 KiB
Markdown
---
|
|
topic: how we work
|
|
status: accepted
|
|
date: 2026-08-28
|
|
deciders: jochen
|
|
reconstructed: false
|
|
---
|
|
|
|
# 19. How this repository works
|
|
|
|
> **Superseded in part — 2026-10-07, by [ADR 0248](0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md).**
|
|
> The paragraph "the index is written, not only generated on demand" no longer holds: a stored list was
|
|
> a line every decision pull request added to one file, so two open at once always conflicted (issue
|
|
> 297). The list of records is generated when it is read, and `02-DECISIONS/README.md` writes only the
|
|
> topics in their reading order. Everything else here stands, including the reading order and the check
|
|
> that every record has a topic one of the README's.
|
|
|
|
*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](0009-modules-and-the-graph.md)) |
|
|
| `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.
|
|
|
|
**A number identifies a record and never changes.** It is not a position, and it cannot be
|
|
both — a position moves when the set changes, and an identity that moves is not one.
|
|
|
|
That is not a preference. Records are referenced from **outside** this repository: code
|
|
comments, commit messages, the knowledge base. Renumbering once cost 96 references across two
|
|
code repositories, and nothing in either would have failed to compile — the comments would
|
|
simply have pointed at the wrong reasoning, which is worse than a broken link because nothing
|
|
reports it.
|
|
|
|
**So the reading order lives in a generated index**, from each record's `topic:` — 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.
|
|
|
|
**And the index is written, not only generated on demand.** A reader looking at the folder on a
|
|
forge sees the folder, not a command. The objection to a written index is that it drifts, and
|
|
that is answered by **checking** it rather than by refusing to write one — which is §5's own
|
|
rule: a rule states how it is checked. A record with no topic, or a topic nobody defined, fails
|
|
the same check, because the quiet failure is a record that vanishes from the order rather than
|
|
appearing in the wrong place.
|
|
|
|
**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/`](../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.
|