Wiki · Architecture & Decisions
Next session brief — deepen the architecture, then resume Phase 2
How to read this page
Three ways to read this page. Precise is the document itself, exactly as it is written in the repository. Plain and Clear were written for this website to help you meet that document — they are about it. They are not it, and they are not evidence.
This is the design record of the part of the estate whose job is to stop the rest of it claiming more than it has measured. It runs to architecture notes, numbered decision records, phase plans, and the results written after each phase ran.
It is for anyone curious how a decision was actually reached — what was considered, what was refused, and what the refusal cost. The decision records are the most durable part: each names one choice, the alternatives, and the consequence accepted in exchange. The failure-modes page is worth the detour, because it states each refusal as something you could go and test rather than as a promise.
Read the architecture page first. It opens by declaring itself part design and part built, which sets the tone for the whole section. Then the first decision record, then whichever phase interests you — read as a pair, the plan and the results page written afterwards, including the phases where a premise turned out to be wrong and the receipt says so.
What it is not: a description of running software, and not a complete record. Three documents from this area were withheld from publication, because they describe private infrastructure or the operator declined them; they are listed as withheld rather than quietly dropped, so you can see that they exist.
Your browser cannot switch reading levels, so the document itself is shown.
Precise — the source document
This is the document. Rendered from the repository at the commit above, with nothing rewritten for the web. A gate re-renders it on every deploy and fails the build if a single byte differs.
This is prep work, not Phase 2. Phase 2 stays pre-registered and untouched until this completes.
Read RESUME.md first for state, then this.
Standing rules for this session (read before acting)
- Speak. Use
mcp__claude-voice__speakon findings, decisions, phase edges, completion, blockage. Adverse results are spoken first, never appended at the end. Confirmed working: Piper, local,en_GB-jenny_dioco-medium. - Converse. Do not dump. One thing at a time. Lead with the outcome in the first sentence. If a long status block is forming, it belongs in TRACK, not in chat.
- Ask, do not assume. Naming, scope and contract changes are the operator's. Speak the question and stop.
- Ground before claiming. Four times this project I reported a replica as canonical or a doc as truth. Verify against the live source and name it.
- Live read only. Nothing in TRACK may be cached or hand-transcribed. If a value cannot be read live, it renders as unknown — never as a guess.
What exists now
| thing | where |
|---|---|
| C4 model of record | workspace.dsl — 15 containers, 31 relationships, 4 views |
| Rendered views | generated/*.svg + *.png, via render.sh (structurizr-cli + PlantUML, both installed) |
| Mermaid projections | views.md — 9 views, render with no tooling |
| Architecture prose | ARCHITECTURE.md — 15 sections |
| Decisions | decisions/ADR-0001..0007, each with a falsifier |
| Phases | phases/PHASE-1.md, PHASE-1-RESULTS.md, PHASE-2.md |
| Live surface | UNI TRACK :8102 — viewer/track/ in UNI.Minecraft; serves /arch/* and /api/arch |
Task 1 — Audit the architecture for accuracy
Cross-check every claim in ARCHITECTURE.md, workspace.dsl and views.md against the running system, not against each other. For each: confirmed, corrected, or NOT_VERIFIED with the reason.
Known to check: port and process claims for all four bodies; the seat list and signal population in Gaia (live, not GAIA.md); the ledger tally (canonical only — the chip replicas are stale by design); the Door's verbs and journey states; the ui/ contract as amended; every SP.* module name actually present in lib/sp/.
Falsifier: any statement in the architecture that cannot be traced to a live read or a named file:line.
Task 2 — Add the missing specification
Currently absent and needed before the Control Plane is built:
- Sequence diagrams (Mermaid, into
views.md, and mirrored in the DSL where it can carry them): register a gate → run paired → observe → review → author verdict → write receipt → append row → Gaia projects; the Door's admission and release; a room/airlock transition with two keys; an emergency stop mid-run; a drift surfacing and its resolution. - Component view — the C4 level below Container, for
SP.ControlPlaneinternals. - Data specification — the ledger entry shape, the receipt shape, and the scene-node contract, each with field types and required/optional, cross-referenced to
gate_row.schema.json. - Failure-mode spec — every refusal in
ARCHITECTURE.md §10as a testable statement. - The
SP.Producerdisambiguation line (ADR-0006) — not yet written.
Task 3 — Drill-down and cross-linking in TRACK
- Every element in the diagram links to its definition — a body to its
ARCHITECTURE.mdsection, a Control Plane part to its phase item, a gate to its receipt. - ADRs cross-link to the elements they govern, and elements back to their ADRs.
- Render the markdown docs in the page rather than serving raw text.
- Surface each falsifier next to the thing it would falsify.
- Make
/api/archcarry the model's parsed elements and relationships so the page can show the graph, not just the pictures.
Constraint: TRACK owns nothing and caches nothing. Every addition is a live read from the real file, carrying that file's path.
Task 4 — Re-render and verify
bash docs/control-plane/render.sh # validate + export + render, all 4 views
cd ~/Documents/UNI.Minecraft
node viewer/gaia/verify_gaia.cjs # expect 12 PASS, 8 drift signals
node viewer/gaia/gaia_lint.cjs # expect 0 violations
node viewer/gaia/replica_ledger_probe.cjs # re-capture replica digests
curl -s http://127.0.0.1:8102/api/arch # index resolves
Do not add a hex dependency, edit mc_test.exs (user-owned), write to evidence/gates.ndjson, or move a P-level.
Exit condition
This brief is complete when the architecture audit is recorded, the missing specs exist, TRACK drills down and cross-links, and every view re-renders clean. Then, and only then, resume phases/PHASE-2.md exactly as pre-registered.
Per ORCHESTRATE-RULES.md §1, record the result and name the next act. Phase 2 ends by writing PHASE-3.md.
sha256 9e6ba7c41cd4ef07 — of the original file, so what was ingested stays checkable.
Plain — written for this website, not the source document
Whoever picks the project up next is the reader here. The brief says at the top what it is not: preparation, not the phase that follows. That phase was written down before any of it began, and stays untouched until this work is done, so none of it has happened yet.
Standing rules come before the work. Speak findings aloud, and speak an adverse result first rather than appending it at the end. Converse rather than dump; a long status block belongs on the live surface, not in chat. Ask rather than assume — naming, scope and contract changes belong to the operator. Ground a claim before making it. The brief counts, without flattery, the times a copy was reported here as the original or a document as the truth. And read live: a value that cannot be read live renders as unknown, never as a guess.
A short inventory follows, the model of record among it. Then four tasks: audit the architecture against the running system, write the specifications still absent, give the live surface drill-down and cross-linking, and re-render and verify. A closing condition says when the brief is finished.
Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 9e6ba7c41cd4ef07
Clear — written for this website, not the source document
A brief for the next working session, and a plan rather than a record. It describes work to be done, and opens by saying that this is preparation and that the following phase, committed in advance, stays untouched until this completes. It also tells the reader which page to read first, for state.
The standing rules come first, which tells you how they are meant to be used. Speak findings, decisions, phase edges, completion and blockage aloud, and put an adverse result first rather than at the end. Converse rather than dump: one thing at a time, outcome in the first sentence, and a long status block belongs on the live surface, not in chat. Ask rather than assume: naming, scope and contract changes are the operator's. Speak the question and stop. Ground before claiming, with an unflattering count of how many times in this project a copy was reported as the original or a document reported as truth. And read live: nothing there may be cached or hand-transcribed, and a value that cannot be read live renders as unknown, not as a guess.
A short table records what already exists: a model of record with its containers, relationships and views; rendered exports; projections that need no tooling. Also the architecture prose; the decision records, each naming what would show it wrong; the phase documents; and the live surface.
Four tasks follow. The first is an audit: cross-check every claim in the architecture prose, the model and the projections against the running system rather than against each other, marking each confirmed, corrected, or not verified with a reason. It lists what needs checking, and names what would show it wrong: any statement that cannot be traced to a live read or to a named file and line.
The second task is the specification still absent and needed before the body is built. Sequence diagrams for the evidence path and for admission, release, a two-key transition, an emergency stop and a drift and its resolution. A view one level below containers for the internals. A data specification for each kind of record the body writes down. Every refusal in the architecture prose restated as a testable statement. And one disambiguation line that has not yet been written.
The third task is drill-down and cross-linking on the live surface. Every element links to its definition. Decisions are cross-linked to what they govern and back again. Documents are rendered in the page rather than served as raw text. Each test is shown beside the claim it would break. And the interface carries the model's parsed elements and relationships, so the page can show the graph, not only the pictures. A constraint is attached: that surface owns nothing and caches nothing, and every addition is a live read carrying the path it came from.
The fourth task is to re-render and verify, with the expected results named in advance. Then a short list of things not to do: no new dependency, no edit to a user-owned test file, no write to the gate record, no move of a confidence level.
The brief closes with its exit condition. It is complete when the audit is recorded, the missing specifications exist, the live surface drills down and cross-links, and every view re-renders clean — and only then does the phase committed in advance resume. The last line carries the rule that a session ends by recording the result and naming the next act.
Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 9e6ba7c41cd4ef07