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 0015
2	Nodes and agents decouple — a node holds no licence; an agent holds credentials and delivery follows its bindings and modality.	jochen	ADR 0015
3	noxflow dissolves; hal/work inherits tasks and workflows.	jochen	ADR 0015
4	Third-party modules leave this repository — they run on the mesh, not of it.	jochen	ADR 0015
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 0016
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 0016
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 0016, 004
14	The lab issues its own certificates, keeping production's two-authority split rather than collapsing it.	jochen	ADR 0016

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	03-DESIGN/01-to-be/00-work-breakdown.md
25	Work in an isolated worktree, never a shared checkout.	jochen	how-we-build §2
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

---

2026-08-23 — how this repository works

#	Decision	Decided	Where
29	Design splits into two layers that are never mixed — 00-as-is describes the mesh that exists, 01-to-be the one being built toward. A design that ships does not move; its as-is counterpart is written and both stand.	jochen	03-DESIGN/README
30	The as-is layer is written from the implementation and the operational record, not from intent, and records shipped behaviour nobody would choose again. An as-is layer that keeps only the good decisions is a brochure.	jochen	03-DESIGN/00-as-is/README
31	HQ is the source of the mesh constitution. The governed page injected into design sessions is derived from how-we-build.md and never edited directly. Same one-source-many-surfaces argument as #27.	jochen	playbook 05
32	Every workflow is a playbook in 00-META/process/, wrapped by a thin skill that defers to it. Agents operate through the playbooks and not outside them.	jochen	process/00-overview
33	Issues get a front door, 04-ISSUES — design-level and governance faults only. Operational lessons stay in the knowledge base, which is indexed on symptoms. This repository is not a second copy of it.	jochen	04-ISSUES/README
34	Decision records are a chronological ledger. Fourteen decisions already taken in implementation were back-filled as records 0001–0014, each marked reconstructed and carrying its evidence; the two existing records renumbered to 0015 and 0016.	jochen	02-DECISIONS/README
35	Status lives in frontmatter. No central status files; cross-cutting views are generated on demand. This file is a ledger of decisions as taken — an index, and the home of decisions too small to warrant a record — and explicitly not a status board.	jochen	process/00-overview
36	The ADR index is generated, not maintained. The hand-written one had already drifted after a single addition.	jochen	02-DECISIONS/README
37	Modules outside the platform core are grouped by domain, not by single function, extending #1. The principle is settled; the domain list deliberately is not.	jochen	ADR 0017
38	The mesh creates no symlinks at all — not by hand, and not by the installer. Centralising who may link narrowed the incident class without closing it, and a derived file is a copy by nature. The position is settled; the staleness mechanism is not.	jochen	ADR 0018
39	Research efforts follow the 00-overview.md convention, with active / graduated / abandoned in frontmatter — the same shape papa-hq uses, so the two repositories read alike.	jochen	01-RESEARCH/README
40	The numbering is the flow. Decisions become 02-DECISIONS and design becomes 03-DESIGN, so a reader following the folder numbers walks the process in the order it happens — research, decision, design. papa-hq numbers these the other way round because 02-DESIGN predated the promotion of adr/, which then took the next free number rather than its place in the sequence; that repository was too settled to renumber and this one was not.	jochen	02-DECISIONS/README
41	00-GENESIS is renamed 00-META, matching papa-hq.	jochen	00-META/README

---

Observations

Things established by measurement that no decision has yet answered now live in 04-ISSUES, one numbered folder each, so they can be diagnosed, owned and closed rather than accumulating in a table nobody can resolve.

Issue	What it means
001	A failed package install does not fail the job. The first thing the lab was asked to install demonstrated the exact fault the lab exists to catch.
002	A declared package can fail purely because the node's index is old, and today that failure is silent.
003	A manifest can appear to restrict a port and restrict nothing.
004	Every certificate experiment on a real node consumes production issuance quota.
005	The repository's only end-to-end pipeline test has been silently dead since 2026-06-04.
006	This repository is not indexed into the knowledge base — the claim that holds up decision 27.

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 0015.
Which context owns the executor.	Open, from ADR 0015.
Catalogue destination — one repository or many.	Open, from ADR 0015. Phase 4.
What hal/sdk keeps after extraction.	Open, from ADR 0015. Phase 3.
Where human agent modality is recorded — which user, on which node, a human agent acts as.	Open, from ADR 0015. Required by the model; not yet stored.