jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
3.0 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-07-10 | jochen | true |
9. The mesh is governed by a constitution, injected where work is decided
Reconstructed after the fact from the evidence cited below.
Context
By mid-2026 the mesh was doing a large share of its own design and implementation work through agents. The rules those agents were expected to follow existed — in operating instructions, in convention documents, in the knowledge base — but they were retrieved: an agent had to know a rule existed in order to look it up.
Rules that must be looked up are followed by whoever already knows them, which is precisely the population that does not need them. The rules being violated were the ones nobody thought to search for.
Considered options
- Documentation plus review. Rejected — it is what existed. Review catches a violation after the work is done, and only if the reviewer knows the rule.
- Lint and automated checks only. Rejected as insufficient, not wrong. A check catches what can be expressed mechanically; most of these rules are about judgement — what belongs in a repository, when a criterion counts as verified.
- A canonical rule set, injected into context wherever work is decided, with a check phase before output is accepted. Chosen.
Decision
A single canonical document states the mesh's non-negotiable rules. It is injected proactively into every eligible design and analysis session — agents do not fetch it, it arrives — and a check phase verifies the session's output against it before the work proceeds.
It is a governed document, not a page. Changing it requires a proposal, sign-off by reviewers who are not the proposer, and a recorded decision. Drive-by edits are reverted.
Scoped override pages may tighten it for a team or product. They may never relax it.
Consequences
- A rule reaches the work whether or not anyone remembered it existed.
- The check phase makes a violation a blocking outcome rather than a review comment.
- Two copies of the same rules now exist: this document, and the reasoning in HQ that earned
them. The enforced copy wins by default, so the reasoned copy quietly stops being true —
which is why
00-GENESIS/how-we-build.mdis now the source and the governed page is derived from it, via playbook05-constitution-sync.md. - Injection costs context on every eligible turn, and grows with the document. Nothing currently bounds that.
- The amendment process requires two reviewers, which a mesh with one human operator satisfies only by counting agents. That tension is real and unresolved.
References
- The governed page was authored 2026-07-10 and carries its own amendment process.
feat(noxflow): HAL architectural conformance gate for reviewer + architect(#296), 2026-06-10 — the check phase, predating the document it checks against.- Knowledge base:
platform/constitution.