hq/DECISIONS.md

Decision ledger

Every decision, in the order it was taken. Append-only — a decision that stops being true is marked superseded and left in place, because the reasoning that was rejected is the expensive half to rediscover.

An entry here is a record, not the reasoning. Anything architecturally significant carries its full context, options and consequences in an ADR; anything still being worked out lives in 01-RESEARCH. This file is the index that makes both findable, and the place small decisions live that never warrant a document of their own.

Columns. Decided is who made the call. Where points at the reasoning. A decision with no pointer is one small enough that this line is the whole record.

---

2026-08-22 — decomposition

#	Decision	Decided	Where
1	The mesh brokers capabilities; nodes host; agents think. Eight bounded contexts replace 33 platform modules.	jochen	ADR 0001
2	Nodes and agents decouple — a node holds no licence; an agent holds credentials and delivery follows its bindings and modality.	jochen	ADR 0001
3	noxflow dissolves; hal/work inherits tasks and workflows.	jochen	ADR 0001
4	Third-party modules leave this repository — they run on the mesh, not of it.	jochen	ADR 0001
5	Documentation lives inside the code repository under hq/.	jochen	Superseded by #27

2026-08-22 — the lab

#	Decision	Decided	Where
6	Phase 0 is a development environment, not a fixture rig — it is what the host-borrowing dev tooling becomes.	jochen	002
7	The delivery trigger is a real forge inside the lab, not a synthetic event — the webhook relay is part of what is under test.	jochen	002
8	A lab node is a system container, promotable to a virtual machine.	jochen	Superseded by #10
9	Adoption is a legacy path and is out of scope. Bringing nodes into being is the lab runner's job instead.	jochen	design
10	A lab node is a virtual machine running the real install. Supersedes #8: the scale argument for system containers was invented rather than required, and a virtual machine dissolves the fidelity question instead of answering it.	jochen	ADR 0002
11	The environment is called the lab.	jochen	—
12	The lab is driven by incus — for virtual machines, snapshots and bridges through one interface, and because it also runs system containers if a scale run is ever needed.	jochen	ADR 0002
13	The simulated public segment uses TEST-NET-3 (203.0.113.0/24). Not cosmetic: an RFC1918 public segment makes the hub test as unreachable and the mesh silently never forms.	—	ADR 0002, 004
14	The lab issues its own certificates, keeping production's two-authority split rather than collapsing it.	jochen	ADR 0002

2026-08-22 — what the lab is for

#	Decision	Decided	Where
15	The module is what is under test; the mesh is the harness. The loop is: change a module, run it end to end, get a verdict.	jochen	design
16	Nothing new drives delivery. A lab mesh has its own coordinator; the pipeline that runs is the real one. A second delivery path would be blind to exactly the faults worth catching.	jochen	design
17	A test runner is a legitimate component used by the coordinator — lab lifecycle and assertion execution. The line is the pipeline: a runner that decides what to build is a fork of the coordinator.	jochen	design
18	The runner has two callers — the coordinator, and a person developing the mesh — so it needs both a run-to-verdict verb and a leave-it-standing verb.	jochen	design
19	A module carries its own assertions, stated once, in the verification stage the coordinator already dispatches. Running them where failing is free is what makes writing them worth doing.	jochen	design
20	A test declares the mesh it needs; size ranges from one node upward, chosen by the question rather than by what the mesh happens to have.	jochen	design
21	The real topology is one test among many, not the baseline. Anything only testable there is a gap in the vocabulary.	jochen	design

2026-08-22 — working agreements

#	Decision	Decided	Where
22	Never install packages by hand. A package is declared in the module manifest and arrives the way every other package does.	jochen	—
23	Never open a pull request unprompted. A permissions list saying it is allowed is not a request.	jochen	—
24	Every merge is a human checkpoint, without exception.	jochen	02-DESIGN/00-work-breakdown.md
25	Work in an isolated worktree, never a shared checkout.	jochen	CLAUDE.md
26	Decisions are recorded here, thoroughly, as they are taken.	jochen	this file
27	HQ is its own repository, hal-hq. Supersedes #5: the original objection was to a fourth knowledge system, which indexing answers rather than location. Cadence, reviewers, and a scope wider than one repository all argue for separation.	jochen	README
28	This repository is public. Written for a reader who is not its author and has no access to the mesh it describes. No routable addresses, real domains, hosting providers, node names, absolute paths, or operational detail useful only to an attacker. Supersedes the previous rule that research may name instances.	jochen	README

---

Observations — not decisions, but they should not be lost

Things established by measurement that no decision has yet answered.

Observed	What it means
A failed package install does not fail the job. Declaring incus produced error: failed retrieving file … 404 from every mirror, then -> error installing repo packages, and the prepare job reported success. The package is absent; the pipeline is green.	The first thing the lab was asked to install demonstrated the exact fault the lab exists to catch. A fix is already written and open as PR #848, unmerged since 2026-08-20.
The package database is stale on at least one node. The install ran without a sync, so it requested a version the mirrors had already superseded — 404 from every mirror.	A declared package can fail purely because the node's index is old, and today that failure is silent.
scope: on firewall rules is read by no code. Declared in five manifests; not part of the rule type. Real scoping is from:.	A manifest can appear to restrict a port and restrict nothing.
The reverse proxy sets no caServer, so certificate issuance targets the public authority's production endpoint rather than staging.	Every certificate experiment on a real node consumes production issuance quota.
test/pipeline/ has been unbuildable since 2026-06-04, when the npm workspace it depends on was removed. Nothing runs it.	The repository's only end-to-end pipeline test has been silently dead for two and a half months.

Deliberately not decided

Recorded so they are not mistaken for oversights.

Question	Status
Which supervision model the mesh adopts — keep the host init system, drop the redundant per-module layer, containerise the daemons, or write a supervisor.	Open. Options costed in 003. No longer gates the lab.
Whether the lab verdict is a workflow guard or an advisory check on the pull request.	Open, and deliberately trivial — a policy detail, changeable in an afternoon, not an architectural choice.
hal/scheduler — infrastructure or part of hal/work.	Open, from ADR 0001.
Which context owns the executor.	Open, from ADR 0001.
Catalogue destination — one repository or many.	Open, from ADR 0001. Phase 4.
What hal/sdk keeps after extraction.	Open, from ADR 0001. Phase 3.
Where human agent modality is recorded — which user, on which node, a human agent acts as.	Open, from ADR 0001. Required by the model; not yet stored.