jschoubben
333356cff3
Jochen asked whether the order made sense. It did not -- it followed when things happened to be decided, which after consolidation is fictional anyway since record 5 alone folds decisions taken across a week. Concretely wrong before: the domain statement sat at 8, after five engineering rules; the constitution was scattered across 5, 12 and 17; the tiers landed at 15, 16, 21 and 22 with process records in between. Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what runs on them and how it gets there (9-10), how it is built (11-16), how it is checked (17-18), how we work (19-23). Two things made this safe rather than free. It is a permutation, not a compaction, so the renames go through temporary names -- otherwise two files want one slot and one is lost. And the reference rewrite is a single simultaneous pass, because almost every number moved into a slot another number was vacating; replacing one at a time would have cascaded and pointed things at the wrong record while still resolving. Verified: 284 [ADR NNNN](path) links across the repository, all with matching text and target. The ordering principle is now stated in 19 rather than left implicit -- the repository already said "the numbering is the flow" about its folders, and there was no reason for the records to be the exception.
89 lines
4.1 KiB
Markdown
89 lines
4.1 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- 02-DECISIONS/0003-agents-are-persistent-employees.md
|
|
- 02-DECISIONS/0020-the-mesh-is-governed-by-a-constitution.md
|
|
---
|
|
|
|
# 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 0003](../../02-DECISIONS/0003-agents-are-persistent-employees.md)).
|
|
|
|
| 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 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md).
|
|
|
|
## 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 0020](../../02-DECISIONS/0020-the-mesh-is-governed-by-a-constitution.md)). 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`](../../00-META/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 0001](../../02-DECISIONS/0001-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement.
|
|
Until it does, this is the shape.
|