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.
70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-22
|
|
deciders: jochen
|
|
reconstructed: false
|
|
supersedes: none
|
|
---
|
|
|
|
# 19. HQ is its own repository, and it is public
|
|
|
|
## Context
|
|
|
|
The mesh's reasoning — mission, research, design, decisions — began inside the code
|
|
repository, under a folder there. The objection to moving it out was specific and good: the
|
|
mesh already has an operational memory and a structured archive, and adding a third store
|
|
repeats the mistake that consolidation was meant to fix.
|
|
|
|
## Considered options
|
|
|
|
1. **Keep it in the code repository.** Rejected, but the objection it rests on is correct and
|
|
is answered rather than dismissed — see Consequences.
|
|
2. **Put it in the structured archive**, alongside the governed documents. Rejected: the
|
|
archive is not reviewable as a diff, and a design argument is exactly the thing that needs
|
|
line-by-line review and a branch.
|
|
3. **Its own repository.** Chosen.
|
|
|
|
## Decision
|
|
|
|
HQ is its own repository, and it is **public** — written for a reader who is not its author
|
|
and has no access to the mesh it describes.
|
|
|
|
Three reasons it is separate:
|
|
|
|
- **The cadence differs.** A decision changes when thinking changes, not when code changes.
|
|
Tying documents to a code branch merges them on the code's schedule.
|
|
- **The reviewers differ.** A design argument is not reviewed the way an implementation is,
|
|
and should not queue behind a build.
|
|
- **The scope is wider than one repository.**
|
|
[ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the
|
|
monorepo; documentation governing several repositories cannot live inside one of them.
|
|
|
|
Being public is not incidental. It is enforceable only because
|
|
[ADR 0003](0003-the-mesh-database-is-the-source-of-truth.md) made the code repository
|
|
node-agnostic: there is no per-node content to leak. Nothing here may carry routable
|
|
addresses, real domain names, hosting providers, node names, absolute paths, usernames,
|
|
credentials, or operational detail useful only to an attacker.
|
|
|
|
The test is whether a paragraph would still teach a stranger running an entirely different
|
|
mesh.
|
|
|
|
## Consequences
|
|
|
|
- A document and the code it describes can no longer land in one commit. Keeping them honest
|
|
is a discipline rather than a mechanism — which is why decisions are recorded as they are
|
|
taken, and why a document stating a rule must say how the rule is checked.
|
|
- Research must state evidence without identifying the mesh it observed. The shape of a
|
|
finding survives anonymisation; the instance does not travel.
|
|
- **The objection is answered by indexing, not by location** — the claim being that these
|
|
documents remain searchable beside everything else, one source with many surfaces.
|
|
**That indexing does not exist.** Checked 2026-08-23, it returns nothing. Until it does, the
|
|
objection stands unanswered and this repository is the third knowledge store 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).
|
|
|
|
## References
|
|
|
|
- Supersedes the earlier position that documentation lives inside the code repository under a
|
|
folder there. That position was never recorded separately and has no record of its own.
|
|
- [`README.md`](../README.md) — the public-repository rule in full.
|