Architecture — the governing reference

The constitution. Before you add a file, move a module, or define a contract, it is governed by something here. Every principle names the established practice it comes from and the CI gate that enforces it — so no rule lives by convention alone. If a rule is not gated, it is aspirational; treat closing that gap as work. Scope note: crm and retrieval are deferred, and there is no memory domain. A workspace is a user-owned git repo (data, not platform code); crm is an application — one entity schema over a workspace (see P11) — not a platform domain. This doc governs what we build now.

​

0. The shape, in one sentence

​

1. Concepts — the vocabulary (use these words precisely)

​

2. Principles — the rules (each has a why, a source, and a gate)

​

3. The structure — render the chart, don’t snapshot it

pnpm arch:viz cluster:<domain|terminal>   # a bundle's services/modules/contracts + the carriers it touches
pnpm arch:viz flow:<id> | path:<carrier>  # a data path | a carrier's writers -> readers (contract per hop)

​

4. The gates (CI — the teeth)

​

5. How we prove a change — the validation pyramid

​

6. Reference shelf (read these to pressure-test a decision)

​

7. When the rules bend (be honest, not dogmatic)

• An adapter is ceremony if it does no vocabulary translation, no dispatch, and unlocks no test seam, over a stable leaf — inline it (P5 has a cost).
• Default to a module. A new service must justify its distribution tax against P10’s forces.
• A README boundary is acceptable for a leaf with no consumers. The moment it has two, gate it (P9).
• shared/-style kernels are allowed but strict — smallest, most stable, most reviewed code; never a junk drawer. If you can’t name the one concern it hides, it’s not a module.

​

8. Development process — how we build (and contribute)

1. Contract first — define/change the port or contracts/*.v1 before the code; the contract is the unit of agreement. (API-first / consumer-driven contracts)
2. Implement behind a port — transports are adapters; the core stays offline-provable. (hexagonal)
3. Prove down the pyramid — L1 golden → L2 unit (mock ports) → L3 integration → L4 live + eval. Cheapest proof first. (test pyramid)
4. Green under the gates is “done” — isolation · graph · exports · schema-conformance · unit. Green or it didn’t happen. (fitness functions)
5. Small PR on trunk — short-lived branch, small diff, gates required to merge. (trunk-based dev / DORA)

• A current plan always exists — the full path from where we are to the goal: the staged route to “done”, each stage with a runnable proof, plus the critical path and what’s parallelizable. It is a maintained doc (kept in the maintainer workspace), not a memory. The plan is the macro expectation; the expectation–reality loop below executes against it.
• Goal vs objective. The goal is the destination — the end of the plan (the release). An objective is the current go — the one waypoint you execute toward now; the plan is the ordered path of objectives to the goal. The objective is the unit of execution and assessment: you are always executing toward exactly one open objective (never drifting), and it closes either expected (result met it → continue with the next planned objective autonomously — do not stop to ask) or unexpected (result diverged → stop, interpret it with the human as learning, root-cause + codify, and update the plan — an unexpected result is exactly what triggers a re-plan). Expected closure flows on its own through the plan; unexpected closure pulls in the human and revises the plan (ADR-0017).
• Planning mode produces or revises that plan before building — decompose the objective into staged proofs, mark the parallel workstreams, set each stage’s definition-of-done. Output = an approved plan. (design-before-build; staged migration)
• Execution mode runs the plan one stage at a time under the expectation–reality loop — instrument-validated, stop-on-surprise.
• The modes interlock. A surprise that root-causes to a principle gap — or a changed objective — loops back to planning: revise the plan, then resume. The plan is living and always current; you are always in one mode or the other, never improvising without a path.

Collapsed: Plan the full path (planning mode) → execute a stage under the loop (execution mode) → on a gap/surprise, re-plan. Never build without a current plan.

1. State the expected behaviour first. Before acting, name what the system should do and what “done” looks like for the current objective — the contract for the work in front of you. You can’t detect a divergence you never defined. (expectation-first; P19/P21 applied to the work itself)
2. Validate cheaply by instrument — but know it’s approximate. Gates, unit/integration tests, the eval/ replay·analyze·benchmark path are fast, reproducible, and run with no human — so they do the broad, cheap filtering. But their pass/fail is a proxy for “actually working”: the proxy can mis-define success (green while broken, red while fine) or mis-interpret the signal (the capture tool once called a healthy gmeet “unhealthy”). Cheap, not definitive — green is necessary, never sufficient (P19).
3. The human is the ground-truth oracle — scarce, and fallible. At the end of the day only a human can finally tell if the thing actually works — deploy the human precisely where cheap tests can’t correctly define success or interpret the signal (real browser behaviour, real-meeting quality). Because the human is the scarcest resource and errs: spend it last and least, hand a minimal, fully-instructed surface (the exact 🧑 step), and cross-validate both directions — a green instrument is provisional until it correlates with real success; a human “it works” / “I topped up the balance” is checked against an instrument (ping the service, census the tape). A human↔instrument disagreement is a signal: usually the instrument’s success-definition is the gap — fix it.
   • Instrumentalise the human’s verdict. Each human judgement is captured as ground truth — a golden (P8), an eval baseline, a recorded expected-vs-actual — so the cheap test is calibrated to the human and the human is needed less next time. (The eval/ completeness·leakage·attribution scores are “is the transcript right?” turned reproducible.)
4. An unexpected error is a STOP. Reality ≠ expectation ⇒ stop. Don’t paper over it, blind-retry, or push past — an unpredicted behaviour is a signal, not a nuisance.
5. Root-cause every surprise — earn the learning with the human, and promote it twice. Each unexpected error is a symptom of a missing/violated principle. Interpret it with the human (the ground-truth interpreter — a learning is never minted from an instrument alone), trace it to the gap, fix the instance, and promote the learning to BOTH (a) the architecture — a principle + its gate + an ADR, so it bites (P9) — and (b) the learnings log (the running ledger, kept in the maintainer workspace of surprise → root-cause → promotion; the log always, even for a practice/candidate with no P-number). This is how the principle-set grows — P18–P21 were each born from one such surprise. (blameless root-cause; evolutionary architecture; ADR-0018)

Collapsed: Expect → instrument → (human: minimal, cross-validated) → stop on surprise → root-cause to a principle → codify. Report facts, not evaluations.