Order the records the way the system is learned
Jochen asked whether the order made sense. It did not -- it followed when things happened to be decided, which after consolidation is fictional anyway since record 5 alone folds decisions taken across a week. Concretely wrong before: the domain statement sat at 8, after five engineering rules; the constitution was scattered across 5, 12 and 17; the tiers landed at 15, 16, 21 and 22 with process records in between. Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what runs on them and how it gets there (9-10), how it is built (11-16), how it is checked (17-18), how we work (19-23). Two things made this safe rather than free. It is a permutation, not a compaction, so the renames go through temporary names -- otherwise two files want one slot and one is lost. And the reference rewrite is a single simultaneous pass, because almost every number moved into a slot another number was vacating; replacing one at a time would have cascaded and pointed things at the wrong record while still resolving. Verified: 284 [ADR NNNN](path) links across the repository, all with matching text and target. The ordering principle is now stated in 19 rather than left implicit -- the repository already said "the numbering is the flow" about its folders, and there was no reason for the records to be the exception.
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
---
|
||||
status: accepted
|
||||
date: 2026-08-23
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
---
|
||||
|
||||
# 21. HQ is the source of the mesh constitution
|
||||
|
||||
## Context
|
||||
|
||||
[ADR 0020](0020-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 0010](0010-delivery.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-how-this-repository-works.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 0020](0020-the-mesh-is-governed-by-a-constitution.md) — the governed page and why it
|
||||
exists.
|
||||
Reference in New Issue
Block a user