# 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](contract-language.md).

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](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:

```sh
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:

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

What that grant does, from a sandbox run:

- `created` by `sam/todo`: `applied`.
- `claimed` by `sam/todo`: `rejected:no_mandate`. `claimed` is a commitment,
  and `:routine` covers only routine verbs.
- After `widened` with 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, since `widened` replaces 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.
