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.
03-DESIGN / 00-as-is
The mesh as it stands. These documents describe what runs, including the parts nobody would choose again — an as-is layer that only records the good decisions is a brochure.
They are written from the implementation and from the operational record, not from intent. Where the two disagree, the implementation wins and the disagreement is stated.
| Document | Covers |
|---|---|
00-overview.md |
The whole in one pass — what a node is, what a module is, how work reaches it |
01-mesh-and-transport.md |
The mesh database, the broker, discovery, and how a call reaches another node |
02-modules-and-manifests.md |
The module, the manifest, and features as the unit of work |
03-provisioning.md |
Declared requirements, provisioners, credentials, and cross-node grants |
04-delivery.md |
Push to running: the three silos, levels, and what a green pipeline proves |
05-runtime-and-installation.md |
The node runtime, its modes, and how a node comes into being |
06-configuration-and-secrets.md |
Managed files, value resolution, and where secrets live |
07-knowledge.md |
The two knowledge stores, and what each is for |
08-agents-and-work.md |
Agents as employees, tasks, workflows, and the meeting model |
09-interfaces-and-observability.md |
How the mesh is reached and watched — tools, board, proxy, health, thoughts |
10-module-catalogue.md |
The catalogue's shape, and what its shape says |
What these documents are not
They are not a runbook. Operational procedure — how to fix one occurrence of something — lives in the knowledge base, which is indexed on symptoms and is the right place to search when something is broken.
They are not exhaustive. A subsystem is described to the depth at which its design is visible; below that is code.