jschoubben
b4607dfc03
Decided after measuring what renumbering actually costs: 96 references in code comments across two repositories, none of which would have failed to compile. They would have pointed at the wrong reasoning, which is worse than a broken link because nothing reports it. So a number identifies a record and never changes. It cannot also be a position -- a position moves when the set changes, and an identity that moves is not one. The reading order moves into an index generated from each record's `topic:`. Six topics, in the order somebody learns the system. The index is WRITTEN rather than only generated on demand, which reverses what this repository previously said. The reason it said otherwise is that a hand-written index drifts -- but a reader looking at the folder on a forge sees the folder, not a command, and the drift objection is answered by checking rather than by refusing to write one. That is §5's own rule: a rule states how it is checked. Two checks, both confirmed to bite. index.py fails when the written order no longer matches the records. records.py fails when a record has no topic or one nobody defined -- the quiet failure being a record that vanishes from the order rather than appearing in the wrong place.
133 lines
6.6 KiB
Markdown
133 lines
6.6 KiB
Markdown
---
|
|
topic: how we work
|
|
status: accepted
|
|
date: 2026-08-28
|
|
deciders: jochen
|
|
reconstructed: 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](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.
|