Concepts
What each moving part is, what it owns and how they connect. Read this first. The rest of the docs assume these words.
- Everyone runs a sidecar. It holds the device key, signs events, keeps the whole log and folds it.
- Tools, adapters and agents talk only to their own person's sidecar, over a unix socket.
- The sidecar checks every event against the contracts before sending it. A rejected event never leaves the machine.
- The relay stores and forwards signed events. It checks membership and feed order, not contracts.
- Every sidecar folds the same log with the same contracts, so everyone sees the same state.
- Contracts are YAML in the governance repo. Every contract file in the active commit is in force.
your Mac shared
┌──────────────────────────────────┐ ┌──────────────────────────────┐
│ your tool ── adapter ─┐ │ │ governance repo (GitLab) │
│ ▼ │ git │ grouping.yaml │
│ Claude Code ─ MCP ─▶ sidecar ◀───┼────────┤ contracts/*.yaml │
│ gromit CLI ────────▶ (signs, │ │ approve/<commit>/<person> │
│ folds, │ └──────────────────────────────┘
│ queues) │ wss ┌──────────────────────────────┐
│ ▲ ───────┼───────▶│ relay wss://relay.example… │
└─────────────────────────┼────────┘ │ stores and forwards events │
│ │ GitLab bridge ─▶ GitLab │
everyone else's ───┘ │ Asana bridge ─▶ Asana │
sidecars, same relay └──────────────────────────────┘
Grouping
A grouping is a team on the bus. The team's is tally. It is defined by
one git repo, the governance repo (acme/tally-governance), holding:
grouping.yaml: who the members are, their device keys, their forge usernames and the bridges. Itscontracts:list is informational: it names the contracts the default agent mandate covers, and decides nothing else.contracts/*.yaml: one file per contract, such aswork-item@1.yaml. Every contract file in the active commit is in force, listed or not.extensions/: reserved for shared extension schemas. Empty today.
grouping: tally
steward: tom
relay: wss://relay.example.com/
members:
- person: tom
forge: { gitlab: tom, asana: "1200000000000001" } # how bridges recognise you
devices:
- { name: tom-laptop, key: "ed25519:0dbf10…" }
# roles: [lead] optional; contracts can grant rights to role:lead
# on_bus: false a person bridges may act for who runs no sidecar
bridges:
- actor: "system:gitlab-bridge"
mirrors: gitlab
repos: { platform: acme/platform, pipelines: acme/pipelines, tools: acme/tools }
contracts: [change-set@0, decision@0]
key: "ed25519:…"
contracts: [change-set@0, decision@0, mandate@0, work-item@1]
governance:
- paths: ["contracts/**", "extensions/**"]
quorum: { steward: true, majority: true }
- paths: ["grouping.yaml#members"]
quorum: { all_except: subject }
- paths: ["grouping.yaml#governance", "grouping.yaml#steward"]
quorum: { unanimous: true }
Changing the rules
Anyone with push access commits to the governance repo's main. Pushing
activates nothing. Members approve with gromit approve <commit>, which
pushes a tag approve/<commit>/<person> signed with their device key. The
newest commit whose approvals meet the governance: quorum for everything
changed since the active commit becomes active. A path no rule names
needs everyone. gromit rules status shows what is still missing.
So adding a contract is a commit adding contracts/<name>@<major>.yaml, then
the steward plus a majority approving it (the contracts/** rule). Also
listing it in grouping.yaml contracts: touches a path no rule names, so
that edit needs everyone's approval. Do it as a separate commit, or leave it
out.
Every event names the rules it was written under: a hash of
grouping.yaml plus the contract files (the bundle). Each event is
judged by the bundle it names. An event naming a bundle more than 24 hours
after the next one took over is rejected as stale_rules.
Sidecar
Each person runs one sidecar per grouping, as a launchd agent
(com.gromit.sidecar). It:
- holds the person's device key and signs every event they publish;
- keeps a clone of the governance repo and follows its active rules;
- keeps the whole event log in
~/.local/share/gromit/<grouping>/gromit.dband queues events while offline; - folds the log through the contracts into current state on every read;
- judges every event before sending it. One its own fold would reject never leaves the machine. The caller still gets the outcome;
- serves a local HTTP API on
~/.local/share/gromit/<grouping>/sidecar.sock, an MCP server for agents (gromit mcp) and thegromitCLI.
Tools, adapters and agents only ever talk to their own person's sidecar. See sidecar-api.md.
Relay
The relay (wss://relay.example.com/) stores every signed event and sends
each one to every connected sidecar. It checks that the signer is a member
under the active rules and that each event is the next one in its author's
feed. It stamps received_at, the one clock every time rule uses. It does
not fold. It also runs the two bridges.
Events
Everything on the bus is an event: one signed act by one actor on one entity. A real one, as the sidecar's event stream shows it:
{
"id": "1220fc4d0bb4…", // hash of the signed fields
"grouping": "tally",
"contract": "work-item@1.1.0",
"rules": "12200d654b0f…", // the bundle it was judged under
"kind": "fact",
"verb": "created",
"entity": null, // absent on the event that creates the entity
"actor": "system:asana-bridge",
"person": "system:asana-bridge",
"author": "ed25519:f50d29e7…", // the signing device key
"seq": 1121, "prev": "12202f1ee820…", // the author's feed: a hash chain
"seen": [], // events the author had seen, for concurrency
"ts": "2026-11-18T15:27:22.617Z", // advisory only
"received_at": "2026-11-18T15:27:23.901Z", // stamped by the relay
"payload": { "title": "chore(infra): rotate kath_home developer IP…",
"repo": "git:platform",
"ext.asana": { "gid": "1220673936359433", "url": "https://app.asana.com/…" } },
"sig": "83ff3781…"
}
- An entity is identified by the id of the event that created it.
Later events name it in
entity. Ids are long. The API and CLI accept any unique prefix. - A response (
accept,approved) names the handshake it answers inresponds_to. - Events are never edited or deleted. A
redactedevent can blank a field's content while keeping the hash chain valid.
Fold
The fold replays every event through its contract and produces the current state: each entity's fields, each open handshake and each event's outcome. Every sidecar folds the same events with the same rules, so everyone sees the same state, whatever order events arrived in. Contract tests check this by folding each test in 12 shuffled orders.
When two events conflict, the one with the lower hash wins and the other
forks. Two people claiming the same work item at once is the usual case.
Each event gets one outcome: applied, suggestion, claim, pending,
fork or rejected:<reason>. See outcomes.md.
Actors
| Actor | Looks like | Who | Signs with |
|---|---|---|---|
| Person | sam |
a member in grouping.yaml |
their device key, via their sidecar |
| Agent | sam/claude, tom/reader |
software acting for a person | the person's device key; needs a mandate |
| Bridge | system:gitlab-bridge |
a mirror of a shared system, listed under bridges: |
its own key; only its listed contracts and repos |
An adapter publishes as its person (sam), or as one of their agents
(sam/todo) if you want its events marked as automated and limited by a
mandate.
Agents and mandates
An agent can do nothing until its person grants a mandate@0. A grant
names scopes such as work-item@1:routine (every routine verb),
work-item@1:commitment (every commitment), work-item@1:claimed (one
verb) or work-item@1:*. Attestations, such as decision@0:inferred, are
only covered by a grant that names the verb. Every verb has a weight:
routine: applies at once.commitment: held aspendinguntil the person ratifies, unless the grant saysratify: none. It lapses afterratify_within, 24h by default.protected: never by an agent. Approving a change set is an example. If a grant covers the verb the result isrejected:requires_human; if none does,rejected:no_mandatecomes first.
gromit local install grants <you>/claude the default mandate: routine
verbs on work-item@1, change-set@0 and decision@0.
Bridges
A bridge is a system actor that mirrors a shared system onto the bus, so nobody needs their own adapter for it. Both bridges run inside the relay:
- GitLab bridge (
system:gitlab-bridge). Each MR in a listed project becomes achange-set@0held by its author, with reviews mirrored asreview_requestedandapproved. A## Decisionssection in an MR description becomesdecision@0events. - Asana bridge (
system:asana-bridge). Tasks on the boards mapped to a bus repo becomework-item@1, with the Asana ids inext.asana. It works both ways: a work item created on the bus in that repo is written to the board.
A bridge acts for a member through on_behalf and finds members by their
forge: usernames. Someone with no mapping isn't mirrored. A bridge can only
publish the contracts and repos grouping.yaml gives it, and only verbs
whose who names bridge.
Adapters
An adapter connects one person's own tool. It runs on their machine,
talks to their sidecar, and publishes as them. The Tiphys adapter
(gromit-tiphys) is the first one. It turns Argonauts batches into work items
and brings tickets back as seeds. An adapter in another language uses the
same API. See writing-an-adapter.md.
Adapters and bridges never publish the same thing twice. The bridge owns
change sets (one per MR). An adapter links its own planning to them through
part_of and never opens one.
Visibility
Every event goes to the whole grouping today. The protocol allows narrower
audiences, but that is switched off until seed:861 is fixed. A narrower
event would break excluded members' copies of the author's feed. The sidecar
refuses an audience narrower than grouping. So publish nothing you wouldn't
show the whole team.