novox/hq

Files

T

jschoubben 77f3a4cea7 Consolidate: 65 decision records to 23

Every remaining cluster merged. Each was one design that had been split across
several records because it was worked out over days rather than at once.

  the node host          8 -> 1    applies not decides, depends on nothing,
                                   per operating system, root service, the
                                   launcher, episodic, what a declaration is,
                                   actions from the bundle only
  a node and how it joins 4 -> 1   what a node is, joining, the link as
                                   security boundary, the enrolment token
  modules and the graph   7 -> 1   everything is a module, no domain modules,
                                   three edges, provisioning, the core library
  substrate and control   6 -> 1   the test, seven contexts, one control plane,
    plane                          the authority is not a database, the named
                                   products, the pinned bundle
  connectivity            3 -> 1   a route is a grant, reachability declared,
                                   filter rules
  delivery                5 -> 1   reconciliation not a pipeline, artifacts,
                                   the three silos, a failed step, the verdict
  the lab                 5 -> 1   (earlier)
  how this repository     10 -> 1  (earlier)
    works

Nothing was dropped. Each consolidated record carries the reasoning of the ones
it absorbs -- the measurements, the incidents, the alternatives rejected --
because that reasoning is the only reason to keep a record at all. What is gone
is the fragmentation: eight files to read to understand tier 0, when tier 0 is
one component.

The four superseded records went too. They existed to point at their
successors, and the successors now contain what they said.

The checker made this safe. Each merge left dangling links -- 38 files after
the host merge alone -- and it named every one. Nothing was found by reading,
and a manual pass would certainly have missed some, including references inside
AGENTS.md which every session loads.

2026-08-28 20:03:24 +02:00

3.0 KiB

Raw Blame History

status, initiated, touches, became

status

initiated

touches

became

active

2026-08-22

03-DESIGN/00-as-is/02-modules-and-manifests.md

03-DESIGN/00-as-is/10-module-catalogue.md

03-DESIGN/01-to-be/00-work-breakdown.md

02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md

001 — Module domain decomposition

Initiated by: jochen, 2026-08-22
Areas touched: every hal/* and noxflow/* module; the pipeline's dependency graph; the knowledge base; agent identity and credentials.

Summary

HAL has 124 modules. That number is not a maintenance problem in itself — it is the symptom of missing bounded contexts. Modules are split not because they model different domains, but because splitting is the only lever the platform offers:

no way to run one daemon on one node without making it a module (hal/claude-licences — one daemon, single-node)
no way to expose two of a kind from one module
no namespace separating the mesh from the software it runs

This effort establishes the current state, the ideal state, and the sequence between them.

Trigger

A night of debugging that produced four fixes and one conclusion. Every fault was a boundary fault:

Per-agent Claude credentials had to be written by the noxflow runtime, because agents.claude_account is in noxflow's database — even though agent identity is a mesh concept and node identity already lives in the mesh registry.
Whether hal/brain may depend on noxflow took three attempts to answer, twice wrongly, because the ownership boundary was never stated.
Authoritative documentation existed in mesh_docs and was not found, while a proposal in repo markdown was invisible to search entirely.

Decisions taken (2026-08-22)

Question	Decision
What should noxflow become?	Decompose into `hal/*` modules; noxflow returns to tasks/workflows
Who owns agent identity?	`hal/agents` — a mesh concept, alongside nodes
Where do third-party apps live?	Out of this repo. They run on the mesh; they are not of it
Knowledge structure	Modelled on `papa-hq`; implementation choice left open

Open questions

Tracked in analysis.md under "Open questions".

Deliberately not decided

Recorded so they are not mistaken for oversights. Each is open, and each comes out of ADR 0015; this effort stays active until they are answered.

Question	Status
`hal/scheduler` — infrastructure, or part of the work context.	Open.
Which context owns the executor.	Open.
Catalogue destination — one repository or many.	Open. Phase 4.
What the shared library keeps after extraction.	Open. Phase 3.
Where human agent modality is recorded — which user, on which node, a human agent acts as.	Open. Required by the model; not yet stored.
Which domains the modules outside the platform core group into.	Open, from ADR 0044, which settles the principle and deliberately not the list.

3.0 KiB Raw Blame History