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: accepted
|
|
date: 2026-08-23
|
|
deciders: jochen
|
|
reconstructed: false
|
|
---
|
|
|
|
# 25. HQ is the source of the mesh constitution
|
|
|
|
## Context
|
|
|
|
[ADR 0009](0009-the-mesh-is-governed-by-a-constitution.md) established a canonical rule set,
|
|
injected into every eligible design session and checked before output is accepted. It lives in
|
|
the knowledge base, where the orchestrator reads it.
|
|
|
|
HQ separately carried a document stating overlapping rules with the reasoning that earned each
|
|
one. Two texts, one enforced and one not.
|
|
|
|
That arrangement has a predictable outcome and it is not a tie. The enforced copy wins by
|
|
default, because it is the one that blocks work. The reasoned copy quietly stops being true,
|
|
and the rules survive without the incidents that justify them — at which point a rule reads as
|
|
arbitrary, and an arbitrary rule is the kind people route around.
|
|
|
|
## Considered options
|
|
|
|
1. **The knowledge-base page is the source; HQ points at it.** Rejected, though it is the
|
|
honest description of what was already happening. It leaves the reasoning downstream of the
|
|
rule, and the reasoning is the part that makes a rule survive a challenge.
|
|
2. **Accept the overlap and let both stand.** Rejected: two authorities is no authority, and
|
|
the drift is silent.
|
|
3. **HQ is the source; the governed page is derived and published from it.** Chosen.
|
|
|
|
## Decision
|
|
|
|
[`00-META/how-we-build.md`](../00-META/how-we-build.md) is the source. The governed page the
|
|
mesh injects is **derived** from it — the rules without the reasoning — and is never edited
|
|
directly.
|
|
|
|
Publishing is a playbook step, not a manual act, and it ends with **reading the page back and
|
|
verifying the change is present**. A publish that reported success and did nothing is exactly
|
|
the failure class this mesh keeps producing
|
|
([ADR 0008](0008-a-failed-step-fails-the-job.md)).
|
|
|
|
Section numbering is stable, because the orchestrator and the review fragments cite sections by
|
|
number.
|
|
|
|
## Consequences
|
|
|
|
- One source, many surfaces — the same argument HQ's separation already rests on
|
|
([ADR 0019](0019-hq-is-its-own-repository.md)), applied to the rules themselves.
|
|
- Each rule keeps the incident that earned it, in a place that is reviewed as a diff.
|
|
- An edit to the derived page survives until the next sync and then vanishes. The playbook says
|
|
so, and nothing mechanically prevents it.
|
|
- **The sync is manual and is the weak point.** An unsynced rule is a rule the mesh does not
|
|
enforce, whatever the source says — so the playbook requires the failure to be stated rather
|
|
than passed over. This is the same class of gap as
|
|
[`04-ISSUES/006`](../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md),
|
|
and it is worth watching for the same reason.
|
|
- The document grew from four rules to seven sections, because it now has to carry everything
|
|
the mesh enforces rather than only what someone thought to write down.
|
|
|
|
## References
|
|
|
|
- [`00-META/process/05-constitution-sync.md`](../00-META/process/05-constitution-sync.md) —
|
|
the sync, including the read-back.
|
|
- [ADR 0009](0009-the-mesh-is-governed-by-a-constitution.md) — the governed page and why it
|
|
exists.
|