jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
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/0012-agents-are-persistent-employees.md
|
|
- 02-DECISIONS/0009-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 0012](../../02-DECISIONS/0012-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 0015](../../02-DECISIONS/0015-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 0009](../../02-DECISIONS/0009-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 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement.
|
|
Until it does, this is the shape.
|