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.
4.1 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | |||
|---|---|---|---|---|---|---|---|
| as-is | implemented |
|
2026-08-23 |
|
Agents and work
The mesh does a large share of its own design and implementation. Agents are how, and the model they run under is the employee model, not a worker pool.
An agent is an employee
An agent is a singular named identity with a home node, a workspace on that node, accumulating memory, and an explicit lifecycle (ADR 0012).
| Property | Meaning |
|---|---|
| Lifecycle state | Active, draining, or retired. Retired agents are kept. |
| Home node | Where its workspace lives. One node per agent. |
| Session cap | How much work it may hold at once. Concurrency is a property of the agent, not a count of copies. |
| Kind | Whether it is hirable, or is a node's own agent and exempt from hiring |
The verbs are explicit: an agent is hired onto a node, reassigned only while idle, and retired by draining first — forcing it is a deliberate act that aborts work in flight.
Surge capacity lives inside the model rather than against it. A template agent is a blueprint with no life of its own; when a queue grows past a threshold it is cloned into a real agent with a lifetime, which drains and retires when that expires. A temporary employee is still an employee.
Because there is a continuing subject, policy becomes possible: an agent that violates a rule can be warned, and a warned agent can be dismissed. A pool cannot be warned.
Some agents are human
There is one kind of participant. What differs is modality — a non-human agent acts through a spawned session and the record; a human agent acts through a shell, a desktop, or a message. Both hold identity, both act, both accumulate memory.
The mesh does not currently record modality completely. Which user, on which node, a human agent acts as is required by the model and not stored — an open question carried over from ADR 0015.
Work
Work is expressed as tasks moving through workflows. A workflow names the states a kind of work passes through and what must be true to leave each one; a task carries its acceptance criteria and its trail.
Several workflow shapes exist for different sizes of work — a single implementation, a larger container of related work, and shapes that add analysis or design stages ahead of implementation.
The area's characteristic defects are transition defects rather than logic defects: a task bouncing between review and implementation because a guard was evaluated on stale state, a result that cannot be recorded in the same act as the transition it justifies. The workflow engine's correctness is about atomicity, and that is where it has been wrong.
Meetings
Some work is decided in a meeting: several agents in turns, with distinct roles, over a template that names the phases.
This is where governance meets execution. The constitution is injected into every eligible meeting turn — agents do not fetch it, it arrives — and a check phase verifies the meeting's output against it before the meeting may proceed (ADR 0009). A named violation blocks progress.
Meeting turns run on the orchestrator's node regardless of where the participating agents are pinned. That is a known divergence between the model and its execution, not a design intent.
What this rests on that is not built
The work domain shares one large schema with several other domains. That is the concrete
instance of a rule stated in how-we-build.md — contexts
integrate through the record, never through a shared schema — being violated by the mesh's
own largest component, and it is the reason work that belongs to one domain keeps having to be
implemented in another.
ADR 0015 dissolves that arrangement. Until it does, this is the shape.