jschoubben
3f6d939930
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.
68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
---
|
|
status: active
|
|
initiated: 2026-08-22
|
|
touches: [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]
|
|
became: [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`](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](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md); 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](../../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md), which settles the principle and deliberately not the list. |
|