novox/hq

Files

T

jschoubben 3f6d939930 Every decision is a record; the ledger is gone

papa-hq has no ledger. Its root is AGENTS.md, CLAUDE.md, README.md, every
decision is a numbered record, and its graduation playbook has no path for
an unrecorded decision. hal-hq now matches.

The ledger's 41 entries classified as: 10 restating a record, 11 restating
design docs, 15 describing how this repository works with the reasoning
sitting in a README rather than anywhere citable, 3 small rules with no
home, 2 superseded stubs. Mostly a copy — and a hand-maintained index, the
exact pattern ADR 0022 had just rejected for the decision index on the
grounds it drifted after one addition. Keeping one copy of that while
removing another is not a position. It also collided by name with
02-DECISIONS/ in any directory listing.

Nothing was dropped. Records 0019-0025 give the repository decisions the
reasoning they never had: HQ is its own repository and is public, design
has two layers, work moves through playbooks, status lives in frontmatter,
issues have a front door, the numbering is the flow, HQ is the source of
the constitution. 0026 records the ledger's own removal.

The three orphan rules went to how-we-build, where a rule is enforced and
keeps the incident that earned it — the package rule was genuinely
unwritten anywhere. Two lab decisions stated only in the ledger went into
the lab design. "Deliberately not decided" went to the research effort and
design document each question actually belongs to.

The chronological view the ledger provided is now generated from record
frontmatter, which is what it was for.

The cost, stated in 0026 rather than glossed: a record is more work than a
table row, so the risk is a small decision going unrecorded because nobody
wanted to write a document. how-we-build takes rules cheaply, which is the
mitigation, not a solution.

2026-08-23 18:17:59 +02:00

3.1 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 0017, which settles the principle and deliberately not the list.

3.1 KiB Raw Blame History