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.
00-META
The northern star. What HAL is, the environment it runs in, and what changes when it works. Every research effort and design decision is checked against this folder.
| File / folder | Purpose |
|---|---|
mission.md |
Vision, mission, and the values that decide arguments |
context.md |
The environment — conditions, not aspirations |
effect.md |
What is different when the work is done |
how-we-build.md |
The rules that hold across the mesh, each one earned. The source of the mesh constitution — the governed page the mesh injects into design sessions is derived from it. |
repos.md |
Where implementation lives, and what each repository owns |
process/ |
The playbooks — how work moves through this repository, for engineers and agents alike |
Rules
- Markdown only.
- Stable by nature. Changes here reflect a genuine shift in intent, not iteration. The one
exception is
how-we-build.md, which changes whenever a rule is earned — and only through its amendment process. - Research and design must be traceable back to what is written here.
- Instance-agnostic. These documents describe the mesh as a concept. No machine names, no counts, no topology.
On the architecture overview in the code repository
The code repository carries an architecture overview predating this folder. It is a useful
description of how the mesh works, and its content now lives — anonymised and checked against
the implementation — in 03-DESIGN/00-as-is/. GENESIS answers why;
that document answered how, which is the design layer's job.
It had also drifted from the implementation in ways worth recording, since both were found by comparing it against the code rather than by anyone noticing:
- It described the pipeline as having a separate builder process and a build stage that packages. Neither was true after 2026-08-04; the documents stayed stale until 2026-08-06 (ADR 0014).
- It listed the mesh as spanning a fixed number of named machines, which is exactly the content this repository cannot carry.
It also lists "symlinks, not copies" as a key design principle, and that is a genuine contradiction rather than a stale detail. The mesh's stated intent is that it creates no symlinks at all — the rule is not merely "only the installer may link", and a founding document elevating linking to a principle points the opposite way from where this is going.
What exists today is that the installer owns and reconciles every link
(ADR 0011) — an as-is fact, recorded in
03-DESIGN/00-as-is/05-runtime-and-installation.md.
Centralising who may link narrowed the incident class; it did not close it. The intent is to
remove the mechanism, recorded as ADR 0018.
A founding document contradicting the direction of travel is precisely the failure this folder exists to prevent.