jschoubben
87f4f29cc6
ADR 0027 — the product is Novox Mesh, shortened to mesh internally. HAL was never chosen: it arrived with the dotfiles repository this grew out of, it is borrowed, and it is borrowed from the canonical untrustworthy machine intelligence, which is an odd flag for infrastructure trusted with credentials. Timing is the substance of the decision, not an aside — the skeleton is not built, so renaming costs a search and replace now and a migration later. Nox is an identity of Novox, and specifically the agent of the MESH rather than of a node. Nodes keep their own identities. Nox addresses them, and a human mostly talks to Nox — which makes it the concrete form of the mission's vision: state an intent, and the mesh works out which node holds the thing. It holds no private channel. The gap this opens is recorded: ADR 0012 binds every agent to a home node, and a mesh-scoped agent has none, so the model needs extending. ADR 0028 — HQ is company-scoped, novox/hq, with the mesh as its first product. Checked rather than assumed: the company organisation already holds live projects that the mesh builds and deploys, so they are tenants rather than peers, and the mesh is the ground they stand on. There is also company work outside the mesh already, which strengthens the case and means the eventual split is closer than "some day" — so each document's scope is fixed now, in a table, making that split mechanical instead of archaeological. The folders are deliberately not restructured yet. The skeleton takes the new vocabulary: mesh-host, mesh-substrate, mesh-control, mesh-surfaces, mesh-catalog. Substrate drops to four services now that identity is a hosted workload rather than a dependency. Research 009 opens the migration, with the reframing that lowers its risk: replace the control plane, do not move the workloads. Their data never moves, so it is re-declared rather than adopted — which keeps adoption out of scope, as the lab design requires. Self-hosting is the last phase, or a failed cutover takes away the means to fix it.
2.9 KiB
Agent instructions — Novox HQ
This repository is the source of truth for the HAL mesh's mission, research, design and
decisions. Implementation lives in the code repositories (see
00-META/repos.md).
Before changing anything here, read the playbooks in
00-META/process/ — every workflow (research, graduation, design
amendment, issues, build handoff, constitution sync) is documented there, and agents operate
through them. Thin skills in .claude/skills/ wrap these playbooks for invocation
(hal-new-research, hal-graduate, hal-new-issue, hal-diagnose, hal-amend-design,
hal-handoff, hal-sync-constitution, hal-status); each defers to its playbook as
authoritative and adds only the mechanical scaffolding.
Ground rules
- Markdown only. No new top-level folders without explicit confirmation.
- Status lives in YAML frontmatter — on research overviews (
status,became), design docs (layer,status,code,updated), issue reports (status,located-in,fixed-by,amended-design) and decision records (status,date,deciders). Never create a central status file; cross-cutting views are generated from frontmatter. 02-DECISIONS/records are immutable. Supersede with a new record; never edit meaning. Fixing a broken link or path is allowed.- Design docs are prose and diagrams only — no code. A manifest field may be named; a manifest may not be pasted.
- Two layers, never mixed.
03-DESIGN/00-as-is/describes the mesh that exists;03-DESIGN/01-to-be/describes the one being built toward. Every design doc says which it is inlayer:. 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. 00-META/how-we-build.mdis the source of the mesh constitution. The knowledge-base constitution page is derived from it — see playbook05-constitution-sync.md. Never edit the derived page directly.
This repository is public
Nothing here may contain routable addresses, real domain names, hosting providers, node
names, absolute paths, usernames, credentials, or operational detail useful only to an
attacker. Use documentation ranges (RFC 5737, RFC 1918) and role names — anchor,
home-server, workstation, laptop, the build node, the broker node.
The test: would this paragraph still teach a stranger running an entirely different mesh?
If yes, it belongs. If it only makes sense to someone who knows this installation, it is
either a note in the wrong place or a disclosure. The full rule is in
README.md.
A rule states how it is checked
If a document states a rule about the mesh, it says how that rule is verified. An unenforced rule is indistinguishable from a wrong one, and costs more, because people believe it.