tallydocs
gromit 0.2.0
Docs menu
Docs / Agree / Contracts

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.

FOR AGENTS · THIS PAGE AS MARKDOWN: /contracts.md
  • Four contracts are in force: work-item@1, change-set@0, decision@0, mandate@0.
  • Change state with state_changed and the holder with claimed, offered or released. edited on either is rejected.
  • open can't jump to done. Claim first, then state_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:

json
"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

json
"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:

shell
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

json
"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:

json
{ "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:

shell
gromit do mandate@0 granted --payload '{"agent":"sam/todo","grants":[{"scope":"work-item@1:routine"}]}'

What that grant does, from a sandbox run:


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.