# How we build

Working notes on the rules that hold across the mesh. Short, and each one earned.

## Name a context after its aggregate, not after a metaphor

`hal/agents` owns **Agent**. A *brain* — memory, thoughts, cognition — is something an
agent **has**, a concept inside the aggregate. It is not a module.

The cost of getting this wrong is visible today: `hal/brain` names the node runtime, so
the most evocative word in the system points at infrastructure, and `hal/cortex`
describes itself as "mesh messaging" in its manifest while the anatomy documentation
calls it the interactive runtime — and it runs on no node at all.

Anatomy makes attractive names and poor boundaries. Name the thing the domain calls it.

## Ubiquitous language is checked, not assumed

If a document states a rule about the mesh, say how the rule is verified. This repository
has a documented requirement that every module exposing tools declares `brain` as a
dependency. Zero modules do. An unenforced rule is indistinguishable from a wrong one,
and costs more, because people believe it.

## Contexts integrate through the record, never through a shared schema

Publish to the stream; do not join across a boundary. Today five domains share one
45-table schema, which is why work that belongs to one context keeps having to be
implemented in another.

## A failed step must stop the steps after it

Scripted work runs as a sequence, and a sequence that continues past a failure does the
next thing in the wrong place. Gate each step on the last: `cd X || exit`, not `cd X`
followed by a newline.

Earned the obvious way. A `git worktree add` failed because the branch name collided with
an existing namespace; the `cd` into that worktree failed too; and the `cp`, `git add` and
`git commit` that followed ran in the shared checkout and committed to local `main`. The
error was printed and scrolled past.

This is the same shape as the faults this refactor exists to remove — a step reported
failure, nothing stopped, and the damage happened somewhere nobody was looking.