The contracts in force
What each contract the tally grouping uses means: its fields, who may change
them, every verb, and who publishes it today. The authoritative text is the
YAML in the governance repo (contracts/*.yaml, also in this repo's
contracts/). This page explains it. For the language itself, see
contract-language.md.
- Four contracts are in force:
work-item@1,change-set@0,decision@0,mandate@0. - Change
statewithstate_changedand the holder withclaimed,offeredorreleased.editedon either is rejected. opencan't jump todone. Claim first, thenstate_changed {to: done}.- Never open a change set. The GitLab bridge owns them. Link your planning with
change-set@0 linked. - Your tool's data goes under one
ext.<tool>key on work items. Never write another tool's key. - Your mandate covers routine verbs. Commitments wait for your person; protected verbs never apply for an agent.
Read a verb table like this. who says which actors may use the verb. A
person who isn't allowed gets their event turned into a suggestion to
someone who is. If nobody else on the bus holds the right, it's
rejected:not_permitted instead. Weight decides what an agent may do (see
"Agents and mandates" in concepts.md).
The vocabulary used in who and rights:
| Word | True when the actor… |
|---|---|
member |
is a person listed in grouping.yaml |
holder / creator |
is the entity's holder / creator |
bridge |
is a bridge listed in grouping.yaml |
human / agent |
is a person, not an agent (a bridge counts as human only when mirroring a forge's human approval) / is an agent |
party |
is one of an open handshake's parties; outside a handshake, one of the entity's parties: (a decision's subject holder and reviewers) |
party_to(x) |
is the person x, or one of their agents |
role:lead |
holds that role in grouping.yaml |
Counts below are from the team's bus on 18 Nov 2026: 679 work items, 21 change sets, 2 mandates and no decisions yet.
work-item@1: a piece of shared work with one holder
Version 1.1.0. Tickets, tasks and batches all land here.
Who publishes it. The Asana bridge, one per task on the mapped boards, with
ext.asana. The Tiphys adapter, one per Argonauts batch, with ext.tiphys.
Anyone, through gromit do or Claude Code.
Fields
| Field | Type | Who may change it | Notes |
|---|---|---|---|
title |
string ≤200, required | creator, holder, bridge | |
repo |
string | creator, holder, bridge | Bus repo, e.g. git:platform. Decides which Asana board the item goes to, and confines bridges. |
description |
markdown | creator, holder, bridge | |
state |
open active blocked done cancelled |
via state_changed |
default open |
holder |
person or null | via claimed, offered→accept, released, bridge assigned |
the one person who has it |
creator |
person | runtime | who published created |
due |
date | holder, role:lead |
|
tags |
set of string | any member | |
links |
set of {rel, ref} |
any member | rel: blocks, blocked_by, parent, child, relates |
attachments |
set of blob | any member | |
comments |
log of {body} |
any member, bridge | append-only |
viewing |
set of person | n/a | presence, not used yet |
ext.<tool> |
anything | holder, bridge | your tool's own data; see below |
State graph: open → active | cancelled, active → blocked | done | open,
blocked → active | cancelled, done → active, cancelled → open. Anything
else is rejected:illegal_transition.
Verbs
| Verb | Kind | Weight | Who | Does |
|---|---|---|---|---|
created |
fact | routine | member, bridge | new item. Sets the payload, creator, state: open, holder: null |
edited |
fact | routine | per field (table above) | changes the fields in the payload. Not state or holder: those have their own verbs, and edited {state: …} is rejected:expr_error: no right lets anyone edit … |
state_changed |
fact | routine | holder, bridge | payload {to!, reason}. Must follow the state graph |
claimed |
transfer | commitment | member, when holder == null |
you become holder, state: active. Concurrent claims: the lowest hash wins, the rest fork |
offered |
handshake | routine | holder | payload {to!}. Completes when to sends accept: they become holder |
released |
transfer | commitment | holder, role:lead |
holder: null, state: open |
linked / unlinked |
fact | routine | member | add / remove one link: payload {item: {rel, ref}} |
attached |
fact | routine | member | adds an attachment |
commented |
fact | routine | member, bridge | payload {body}, appended |
assigned / unassigned |
fact | routine | bridge only | the tracker's assignee becomes / stops being holder |
Plus the built-ins every contract has: accept, reject, withdraw (answer
a handshake) and redacted.
Extensions: ext.<tool>
work-item@1 allows extensions. Any key starting ext. is carried untouched
and folded like a field. Holder and bridge may write it, and the creator may
set it on created. Use one key per tool and put whatever you like under it:
"ext.asana": { "gid": "1220673936359433", "project": "1210763901085017", "url": "https://app.asana.com/…" },
"ext.tiphys": "batch:b240",
"ext.todo": "t3"
That key is how your adapter finds its own items again. Don't write another tool's key.
A real one
"12200050de2c…": {
"type": "work-item@1#work_item", "layer": "state", "audience": "grouping",
"fields": { "title": "Cache the pricing lookups", "repo": "git:platform",
"state": "open", "holder": null, "creator": "system:asana-bridge",
"comments": [], "links": [], "tags": [], "attachments": [], "viewing": [],
"ext.asana": { "gid": "1211851311343366", "project": "1210763901085017",
"creator": { "gid": "1209570392766091", "name": "Aaron" }, "url": "…" } }
}
Answering an offer
offered opens a handshake. Its outcome is pending until the person
offered answers it with the handshake's id:
gromit inbox # lists it, with the command
gromit do work-item@1 accept --responds-to <offer id> # or reject; the offerer can withdraw
change-set@0: one reviewable set of code changes
One forge MR. Review is a handshake bound to head_sha, so a new push resets
approvals.
Who publishes it. The GitLab bridge opens and syncs one per MR in the
mapped projects, held by the MR's author. Tools never open change sets. They
link their own planning to the bridge's. linked is the only verb anyone
may use on a change set they don't hold: edited and evidence_added on
someone else's become suggestions to them.
Fields
| Field | Type | Who may change it | Notes |
|---|---|---|---|
repo |
external_ref, required | holder | git:platform |
forge_url, source_branch, target_branch, base_sha, head_sha, forge_state |
bridge only (authority: bridge) |
a person setting one gets rejected:authority_bridge |
|
title |
string, required | holder | |
summary |
markdown | holder | |
holder |
person | transfer | the author, on or off the bus |
produced_by |
actor | runtime | who opened it |
reviewers |
set of person | holder | |
part_of |
set of ref | any member | links to planning: tiphys:batch:b240, a work item id… |
evidence |
log of {kind, result, uri, summary, at_sha!} |
holder, bridge | kind: test, run, ci, screenshot, review, log; result: pass, fail, flag |
review_state |
not_requested in_review changes_requested approved |
runtime | from the review handshake |
Verbs
| Verb | Kind | Weight | Who | Does |
|---|---|---|---|---|
opened |
fact | routine | member, bridge | new change set |
synced |
fact | routine | bridge | new head_sha etc. Reopens a met review |
edited |
fact | routine | per field | |
linked |
fact | routine | member | adds to part_of |
evidence_added |
fact | routine | holder, bridge | appends evidence |
review_requested |
handshake | routine | holder, bridge | parties: reviewers, quorum 1, a human who isn't the holder |
approved |
response | protected | party, bridge | completes the review. Agents can't |
changes_requested |
response | protected | party, bridge | payload {reason!}. Counts against the review |
A real one
"12200c569f02…": { "type": "change-set@0#change_set", "fields": {
"repo": "git:platform", "holder": "tom", "produced_by": "system:gitlab-bridge",
"forge_url": "https://gitlab.com/acme/platform/-/merge_requests/481",
"forge_state": "merged", "source_branch": "argo/b240/i797", "head_sha": "b5bd65c8…",
"part_of": ["tiphys:batch:b240", "tiphys:item:i797"],
"review_state": "not_requested", "reviewers": [], "evidence": [], "summary": "Drops the…" } }
decision@0: a decision attached to any subject
A decision about a change set, a work item or anything else with an id. Only
title, choice and because are required. The subject's holder states a
decision. Anyone else can only infer one, as a claim until the holder
confirms it.
Who publishes it. The GitLab bridge, from a ## Decisions section in an
MR description. The Tiphys adapter, for decisions accepted at Finish, and as
<you>/reader for decisions inferred from reading others' MRs.
Fields
| Field | Type | Notes |
|---|---|---|
subject |
ref, required | the entity it's about. Its holder holds the decision |
title, choice |
string, required | |
because |
string, required, redactable | |
instead |
set of {label, summary, consequences} |
the options not taken |
forecloses |
string, redactable | |
confidence |
low medium high |
|
door |
one_way two_way |
how hard it is to reverse |
anchors |
set of "[component] path:12-30@sha" |
|
at_sha |
hash | the code version anchors point at |
supersedes |
ref to a decision | |
basis |
stated inferred confirmed |
runtime |
claim |
unconfirmed confirmed amended disputed |
runtime, inferred only |
state |
open made accepted reversed superseded |
default made |
Verbs
| Verb | Kind | Weight | Who | Does |
|---|---|---|---|---|
raised |
fact | routine | the subject's holder (or their agent); a bridge on their behalf | states a decision. An agent can't raise a one_way door as made: raise it open |
made |
fact | commitment | subject's holder | open → made with {choice!, because!} |
superseded_by |
fact | routine | subject's holder | payload {by!} |
accepted / reversed |
fact | protected | a human party who isn't the holder (reviewers) | reviewer's verdict |
inferred |
attestation | routine | a member who isn't the holder | a claim. At most 8 per subject per at_sha. Agents need a grant naming decision@0:inferred itself |
confirmed / amended |
response | commitment | subject's holder | answers an inferred. Becomes stated |
disputed |
response | routine | holder or party | payload {reason!} |
mandate@0: what an agent may do for its person
Default deny. An agent with no active mandate gets rejected:no_mandate for
everything.
Fields
person (runtime), agent (required, e.g. sam/claude), parent,
grants (set of {scope, ratify, when}), budgets (set of
{scope, max, per}), ratify_within (default 24h, max 7d), expires,
state (active revoked expired).
A scope is contract@major:verb, contract@major:routine /
:commitment / :protected (every verb of that weight) or
contract@major:*. Attestations (decision@0:inferred) are covered only by
a scope naming the verb. ratify is by_weight (the default:
commitments wait for the person), required (everything waits) or none.
Verbs
| Verb | Weight | Who | Does |
|---|---|---|---|
granted |
protected | a human | a new mandate for one of their agents |
widened |
protected | the person | replaces grants with the payload's. Resend every grant you want to keep |
narrowed |
routine | the person or their agent | fewer. Must only shrink |
revoked |
protected | the person | at once, and cascades to sub-agents |
delegated |
routine | the agent itself | a sub-mandate that only shrinks |
ratified |
protected | the person | approves an agent's pending commitment |
A real one, from gromit local install:
{ "agent": "george/claude", "person": "george", "state": "active", "ratify_within": "24h",
"grants": [ { "scope": "work-item@1:routine" }, { "scope": "change-set@0:routine" },
{ "scope": "decision@0:routine" } ], "budgets": [] }
Grant an adapter its own agent identity:
gromit do mandate@0 granted --payload '{"agent":"sam/todo","grants":[{"scope":"work-item@1:routine"}]}'
What that grant does, from a sandbox run:
createdbysam/todo:applied.claimedbysam/todo:rejected:no_mandate.claimedis a commitment, and:routinecovers only routine verbs.- After
widenedwith both grants,{"grants":[{"scope":"work-item@1:routine"},{"scope":"work-item@1:claimed"}]}:pending, until Sam ratifies or 24h pass. With"ratify":"none"on the claimed grant it applies at once. Sending only the new grant would have dropped the routine one, sincewidenedreplaces the list. - Anything by
sam/other, which has no mandate:rejected:no_mandate.
Contracts in this repo but not in force
red-list@0 (protected surfaces) and meal-plan@0 (a test of the language
against another domain) live in this repo's contracts/ for tests only. The
team's grouping hasn't adopted them.