jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
114 lines
6.6 KiB
Markdown
114 lines
6.6 KiB
Markdown
# HAL — HQ
|
|
|
|
The single source of truth for what the HAL mesh **is**, what it is **becoming**, and
|
|
why. Implementation lives in `modules/`; the reasoning behind it lives here.
|
|
|
|
## Structure
|
|
|
|
| Folder | Purpose |
|
|
|--------|---------|
|
|
| [`00-META`](00-META/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. The northern star for every decision. |
|
|
| [`01-RESEARCH`](01-RESEARCH/) | Active and historical investigations, before they harden into design. |
|
|
| [`02-DECISIONS`](02-DECISIONS/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. |
|
|
| [`03-DESIGN`](03-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](03-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](03-DESIGN/01-to-be/) — the one being built toward. |
|
|
| [`04-ISSUES`](04-ISSUES/) | The front door for "something is wrong" at the level of design or governance. |
|
|
| [`DECISIONS.md`](DECISIONS.md) | The ledger: every decision as it was taken, indexing the records and holding the ones too small to warrant one. |
|
|
|
|
**The numbering is the flow.** Research produces a decision; the decision authorises a design.
|
|
That is why decisions are `02` and design is `03` — a reader following the numbers walks the
|
|
process in the order it happens.
|
|
|
|
## The flow
|
|
|
|
```
|
|
idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo)
|
|
│ │ │
|
|
│ │ └─► 03-DESIGN/00-as-is once shipped
|
|
│ └────► abandoned (recorded, kept)
|
|
└─(small/obvious, decision recorded in DECISIONS.md)────► 03-DESIGN directly
|
|
|
|
symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment
|
|
|
|
00-META/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions
|
|
```
|
|
|
|
Implementation lives in the code repositories — see
|
|
[`00-META/repos.md`](00-META/repos.md). Every workflow is a playbook in
|
|
[`00-META/process/`](00-META/process/); agents operate through them and not outside them.
|
|
|
|
## Rules
|
|
|
|
- Markdown only.
|
|
- No new top-level folders without explicit confirmation.
|
|
- Knowledge flows `GENESIS → RESEARCH → DESIGN`. Research graduates into design only after
|
|
analysis against GENESIS confirms alignment, and only through a recorded decision.
|
|
- **Status lives in frontmatter**, never in a central status file. Cross-cutting views are
|
|
generated on demand, never hand-maintained.
|
|
- **GENESIS and DESIGN are instance-agnostic.** They describe the mesh as a concept — no
|
|
machine names, no counts, no topology. A reader must not be able to tell how many nodes
|
|
the author happened to have.
|
|
- **RESEARCH describes real observations, but never identifies the mesh it observed.**
|
|
Evidence is what makes research worth reading, and the shape of a finding survives
|
|
anonymisation intact — *a node publicly named but behind a household NAT* carries the whole
|
|
lesson without naming anything.
|
|
- **The as-is layer records what is, not what should be** — including behaviour nobody would
|
|
choose again. A layer that keeps only the good decisions is a brochure.
|
|
- A document that states a rule about the mesh should say how that rule is **checked**.
|
|
This repository has a rule requiring every capability-exposing module to declare the core
|
|
runtime as a dependency; zero modules do. An unenforced rule is indistinguishable from a
|
|
wrong one.
|
|
|
|
### This repository is public
|
|
|
|
Written for a reader who is not its author and has no access to the mesh it describes.
|
|
Concretely, nothing here may contain:
|
|
|
|
- **routable addresses, real domain names, hosting providers, or node names** — use the
|
|
documentation ranges (RFC 5737 `203.0.113.0/24`, RFC 1918) and role names such as `anchor`,
|
|
`home-server`, `workstation`, `laptop`
|
|
- **absolute paths** from anyone's machine, usernames, home directories, or email addresses
|
|
- **credentials in any form**, including lengths or hashes of live secrets
|
|
- **operational detail that is only useful to an attacker** — which host is the VPN hub, on
|
|
which port, which node is reachable only through a forwarded port
|
|
|
|
Private-range addresses and the overlay plan are fine: they describe a pattern, not a target.
|
|
|
|
The test is whether a paragraph would still teach something to a stranger running an entirely
|
|
different mesh. If it would, it belongs. If it only makes sense to someone who knows this
|
|
particular installation, it is either a note in the wrong place or a disclosure.
|
|
|
|
## Why this is its own repository
|
|
|
|
It began inside the code repository, on the reasoning that HAL already has a mesh-native
|
|
knowledge store and that adding a fourth knowledge system would repeat the mistake this
|
|
folder was created to fix.
|
|
|
|
**That objection was about a fourth knowledge *system*, and the answer offered was indexing
|
|
rather than location** — that these documents would be indexed into the knowledge base, so a
|
|
symptom search returns them beside everything else. One source, many surfaces. Where the source
|
|
is authored is then a separate question.
|
|
|
|
**That indexing does not exist.** It was checked on 2026-08-23 and returns nothing; it appears
|
|
never to have existed. Until it does, the objection stands unanswered and this repository is
|
|
the fourth knowledge system it was argued not to be. Recorded as
|
|
[`04-ISSUES/006`](04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md), and
|
|
left standing here rather than quietly reworded, because a claim that held up a decision and
|
|
was never checked is precisely the failure this repository exists to name.
|
|
|
|
Answered separately, a repository of its own is the better home:
|
|
|
|
- **The cadence is different.** A decision changes when thinking changes, not when code
|
|
changes. Tying documents to a code branch means they merge on the code's schedule.
|
|
- **The reviewers are different.** A design argument is not reviewed the way an
|
|
implementation is, and it should not queue behind a build.
|
|
- **The scope is wider than one repository.** [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the
|
|
monorepo entirely. Documentation that governs several repositories cannot live inside one
|
|
of them.
|
|
|
|
The trade is real and worth naming: a change to a document and the change to the code it
|
|
describes can no longer land in one commit. Keeping them honest is a discipline now rather
|
|
than a mechanism — which is why [`DECISIONS.md`](DECISIONS.md) records decisions as they are
|
|
taken, and why a document that states a rule should say how the rule is checked.
|
|
|
|
Recorded as decision 27 in [`DECISIONS.md`](DECISIONS.md).
|