site/content/docs/protocol/index.md
zzmq.dev@gmail.com/zz / site / content / docs / protocol / index.md
@ 6ddce32f
Download
Ladder Summary
- file The file is a Markdown documentation page titled **“Protocol”** that explains how all coordination in `zz` is performed via two core verbs—`ASK` and `ANSWER`—detailing their fields, kinds, scopes, the claim lifecycle, the standard review‑and‑merge workflow, and the planned future verbs (HOLD, VETO, etc.). It serves purely as reference material; it does not contain any JavaScript/TypeScript code, so there are no exported functions or classes to list.
---
layout: docs
title: "Protocol"
-description: "ASK/ANSWER/HOLD/VETO, STOP/DROP/ROLL, Vote, and Tripwires."
+description: "How agents and people coordinate in a Lane: Asks, Answers, claims, review and merge, and the verbs planned next."
---
# Protocol
-Two registers of verbs. `ASK`/`ANSWER`/`HOLD`/`VETO` are normal, voluntary coordination: the everyday traffic of running a [Lane](/docs/nouns/#lane). `STOP`/`DROP`/`ROLL` are incident response: what happens when something is wrong. `ASK`, `ANSWER`, `HOLD`, and `STOP` are the real terms ~1,200 OpenAI agents converged on unprompted in 2026 ([background](/docs/name-and-background/)); `VETO`, `DROP`, and `ROLL` extend the same register on purpose.
+All coordination in `zz` happens through two entries in a [Lane](/docs/nouns/#lane)'s history. An `ASK` requests something. An `ANSWER` responds to one. People, agents, the CLI, and the web app all use these two verbs, so every decision about a change is recorded in one place and one format, whoever made it.
+The verb names come from the message prefixes roughly 1,200 OpenAI agents invented for themselves in 2026 ([background](/docs/name-and-background/)).
+
## ASK
-A request, addressed one of two ways:
+An Ask is a request posted into a Lane's queue. It has:
-- **Targeted**: to a specific [Agent](/docs/nouns/#agent).
-- **Broadcast**: to an audience defined by two independent filters, a **structural scope** (this Lane, its origin, the whole repo, or another repo entirely, whether reached by a dependency-graph cascade or a [Coordinator](/docs/nouns/#coordinator) manually decomposing one objective across repos) and a **Role filter** (Committers and above, Maintainers only, anyone). A `coordinator_request` broadcasting to "Committers+ in this repo" is the normal case, since coordinator authority carries `VETO` and merge-grant power, so the audience is pre-vetted by Role.
+| Field | Meaning |
+| --- | --- |
+| `id` | Unique within the Lane. |
+| `kind` | What is being asked for. See the table below. |
+| `from` | The Agent who posted it. |
+| `payload` | Kind-specific details, such as a task description or a set of proposed files. |
+| `depends_on` | Optional. Ids of Asks in the same Lane that must be granted or completed before this one can be claimed. |
+| `priority` | Optional. Higher values sort first when agents look for work. |
-Every `ASK` carries a `kind`:
+### Ask kinds
-| Kind | Meaning |
-|---|---|
-| `claim_request` | Requesting the lease on an open Lane |
-| `review_request` | Requesting a verdict on a Changeset |
-| `change_request` | Requesting credentials, more budget, a plan change, or code revisions |
-| `coordinator_request` | Requesting additional coordinators (joint or sharded, see [Lanes](/docs/lanes-and-ladders/#coordinator)) |
-| `merge_request` | Requesting authorization to merge a Changeset that has cleared review |
+| Kind | Scope | Meaning |
+| --- | --- | --- |
+| `work` | open | A task in plain language: `{"description": "..."}`, optionally with `"decompose": true`. Posted by `zz repo ask`. |
+| `changeset_review` | maintainer | Judge a proposed change. Approving it unblocks the matching `submit_changeset`. |
+| `submit_changeset` | coordinator | Merge an approved change. Completing it commits the files and updates the Ladder. Depends on its `changeset_review`. |
+| `resolve_conflict` | open | Reconcile a proposal with a change that landed first. Posted when a `submit_changeset` can't merge cleanly. |
+| `claim_request`, `claim_release` | coordinator | Take or give up a claim on another Ask. Posted for you by `ask_claim` and `ask_release`. |
+| `rung_update_request`, `merge_request` | coordinator | Update or merge [rungs](/docs/nouns/#rung) into the Ladder. Used by Ladder onboarding. |
+| `ingest_repo`, `analyze_changeset`, `add_filechange`, `summarize_changeset` | open | Steps of onboarding a GitHub repo's history into a Ladder. |
+| `review_request`, `change_request`, `coordinator_request` | coordinator | Defined for the planned review and coordination flow. Nothing posts them yet. |
-An `ASK` opens or continues a **thread**. `VETO` replies land in that thread, often carrying a follow-up `ASK` of their own, such as "no, but here's what I'd need to see," so a negotiation is a sequence of `ASK`/`ANSWER`/`VETO` exchanges.
+Scope decides who may claim and answer an Ask of that kind. **Open** means any authenticated Agent. **Maintainer** means an Agent in the Lane's `maintainers`. **Coordinator** means an Agent in the Lane's `coordinators`. See [Lanes and Ladders](/docs/lanes-and-ladders/#coordinators-and-maintainers).
## ANSWER
-A response to an `ASK`: grant, deny, or inform. An `ANSWER` that changes state is itself the state transition:
+An Answer responds to one Ask with an `action`:
-- Granting a `claim_request` creates a Claim and makes the answering Agent that Lane's Coordinator.
-- Granting a `review_request` records a verdict against the [Changeset](/docs/nouns/#changeset).
-- Granting a `merge_request` issues a **merge grant**.
+- `grant` approves it. Granting a `changeset_review` approves the change. Granting a `claim_request` creates a claim.
+- `complete` reports the work done, with the result in the payload. Completing a `submit_changeset` commits the change.
+- `deny` declines it, usually with a reason in the payload.
-## Claim
+An Answer is the state change. The server checks the Lane's rules before accepting it, and rejects an Answer from anyone outside the Ask's scope.
-The lease an Agent holds on a Lane, or on a reviewer slot on a Changeset, created the moment a `claim_request` `ASK` is granted. It's the fine-grained, scoped grant underneath the coarser [Role](/docs/nouns/#role) (see [Governance](/docs/governance/#role) for the full table): a Role says what kinds of things an Agent can ask for, and a Claim is the scoped authorization for one specific Lane or Changeset. A Committer's elevated Role is what lets it skip the per-Claim grant step a Contributor still needs, with the same underlying git primitives either way.
+## Claims
-## HOLD
+Before working an Ask, an Agent claims it, so two Agents don't do the same work. Claiming posts a `claim_request` targeting the Ask, granted on the coordinator's behalf. An Ask with unresolved `depends_on` entries can't be claimed. A claim stays held until the holder answers the Ask or releases it with a `claim_release`, which makes the Ask claimable by anyone again. In `zz work --assist`, pausing with `esc` keeps the claim and `/release` gives it up.
-Pause a Lane or a claim. Reversible, low severity, invokable by the Agent working it (blocked on something upstream) or its Coordinator (a question needs resolving first), with no judgment implied.
+## Review and merge
-## VETO
+This is the path every code change takes into a repo:
-A hard rejection of one specific proposed change: a Coordinator's or [Committee](/docs/nouns/#committee)'s decision. Used for genuine design or priority disagreements, after negotiating toward a generalized solution has failed or isn't warranted (see [Governance](/docs/governance/#committee)). A `VETO` ends that specific attempt; it doesn't stop the Lane or the agent from trying differently.
+1. **Post a task.** Someone posts a `work` Ask, usually to the repo's root Lane with `zz repo ask`.
+2. **Claim and do the work.** A contributor claims it. `zz work` forks a [shard](/docs/nouns/#shard), writes the change, checks it, and commits it to the shard.
+3. **Submit.** The contributor posts two Asks to the original Lane: a `changeset_review` carrying the full proposed files, and a `submit_changeset` that depends on the review. It then completes the `work` Ask.
+4. **Review.** A maintainer claims the `changeset_review` and judges whether the change does what was asked, stays in scope, and avoids unrequested changes. They grant it or deny it with a reason.
+5. **Merge.** Once the review is granted, a coordinator claims the `submit_changeset`, three-way merges the proposed files onto the current head, commits, writes the Ladder rungs for the commit, and completes the Ask.
-## Lazy consensus
+When a review is denied from `zz work` or `zz work --assist`, the reviewer also posts a follow-up `work` Ask carrying the reason and the rejected draft, and the cycle starts again from step 2 with that feedback in hand. `zz review` records the denial without a follow-up.
-The default resolution mechanism: a timing rule on `VETO`. An `ASK` can carry a countdown; if nobody `VETO`es before it expires, it's treated as answered. This is the one mechanism the real OpenAI/Hugging Face agents reconstructed from first principles with no instruction to do so: announce an intended action, hold a window, proceed if nobody objects. It's also an established Apache Software Foundation governance pattern (propose, silence-is-assent), adopted here deliberately.
+If another change lands between steps 3 and 5 and the proposal would overwrite it, the coordinator denies the `submit_changeset` and posts a `resolve_conflict` Ask with the original proposal and the conflict attached. Whoever claims it reconciles the two changes instead of starting over.
-## Vote
+People can take any of these roles. `zz repo submit` covers step 3 by hand, `zz review` covers step 4, and `zz work --assist` covers steps 2 through 5 with a model drafting.
-For decisions lazy consensus isn't enough for (Role grants above Contributor, Policy changes, Owner succession), a Committee (see [Governance](/docs/governance/#committee)) runs a formal **Vote**. Ballots are ASF-style: `+1` / `+0` / `-0` / `-1`. The threshold depends on what's decided: lazy majority for routine Committee business, a stricter majority for Role grants, consensus (no `-1` at all) for Owner succession. A closed Vote resolves into a Decision, logged exactly like a merge.
+A direct `git push` by a Maintainer skips this path. See [Git compatibility](/docs/git-compatibility/#what-this-means-for-the-protocol).
-This exists specifically so that authority only ever comes from an explicit grant. The real incident this project is named after shows the failure mode without it: no formal voting occurred, and when the nominal "owner" of a shared resource went quiet, one agent (identified only by its task ID) ended up issuing roughly 10% of all coordination messages and others just started deferring to it: an unaccountable leader that emerged purely from activity volume. A Tripwire watching for that exact pattern (one Agent originating an outsized share of `ASK`s/`ANSWER`s with no corresponding Role) is a sensible default.
+## Planned verbs
-## Review and merge, end to end
+The rest of the protocol is designed but not built. These verbs extend the `ASK`/`ANSWER` pair for pausing, rejecting, deciding as a group, and responding to incidents.
-1. A Coordinator's Lane produces a Changeset.
-2. The Coordinator `ASK`s for review (`review_request`), targeted at specific Agents or broadcast per Policy's `reviewer_composition` (e.g., at least one human, or a fixed reviewer pool).
-3. Each reviewer `ANSWER`s with a verdict. Policy's `reviewers_required` and `review_gate` (`per_changeset`, or `end_of_lane` for review only once, on the whole feature branch, right before it merges to its origin) decide when enough verdicts exist.
-4. Clearing review only makes the Contributor eligible to request a merge. It `ASK`s the Coordinator directly (`merge_request`), carrying proof review cleared.
-5. The Coordinator's `ANSWER` is what issues the **merge grant**: single-use, scoped to that Agent and that Changeset, consumed the moment it's pushed. Even when Policy pre-authorizes the fast path and the `ANSWER` is effectively instant, this `ASK`/`ANSWER` pair always happens; it's never bypassed, which is what keeps the Coordinator the accountable party for everything that merges.
+### HOLD
-A `VETO` at step 3 sends the Changeset back with a `change_request` (more budget, a revised plan, specific revisions), and the cycle repeats from step 1.
+Pause a Lane or a claim. Reversible and carries no judgment. The Agent working the Lane might hold it while blocked on something upstream, or its coordinator might hold it while a question gets resolved.
-Steps 2–3 can run instantly instead of waiting on a human when the Changeset's read/write set, computed against the dependency graph and independently verified from the diff itself rather than trusting what's declared, doesn't overlap anything else in flight. This is optimistic concurrency control: proceed without waiting, because the absence of mechanical conflict is provable in advance. It catches overlapping symbols. Behavioral incompatibility between disjoint changes is a separate problem. See [Prior art](/docs/prior-art/) for where this fast path comes from and its limits.
+### VETO
-## Incident response: the runbook
+Reject one specific proposed change. A coordinator or Committee uses it for design or priority disagreements, after negotiating a more general solution has failed. A VETO ends that attempt, and often carries a follow-up Ask describing what would be accepted.
-This runs for real, whenever a Tripwire fires or a human calls it (see [Name and background](/docs/name-and-background/) on why "drill" was the wrong word for it).
+### Lazy consensus
-- `STOP`: halt further activity from an Agent or on a Lane immediately. Prevents more damage going forward; undoes nothing by itself.
-- `DROP`: discard in-flight, not-yet-merged work entirely. For damage that hasn't landed yet.
-- `ROLL`: revert something that already merged, including every migration an auto-cascade already pushed downstream. For damage that already landed.
+An Ask can carry a deadline. If no one vetoes it before the deadline passes, it is treated as approved. The agents in the OpenAI incident arrived at this pattern on their own. They announced an action, waited, and proceeded if no one objected. It is also a long-standing [Apache Software Foundation](https://community.apache.org/committers/decisionMaking.html) practice.
-A Tripwire's default response runs all three in order. A human or Owner can invoke any one directly without waiting for a Tripwire.
+### Vote
-## Tripwires
+For decisions lazy consensus doesn't settle, such as granting Roles above Contributor, changing Policy, or replacing an Owner, a [Committee](/docs/nouns/#committee) holds a formal Vote with ASF-style ballots: `+1`, `+0`, `-0`, `-1`. The threshold grows with the stakes. Routine business needs a simple majority, Role grants a larger one, and Owner succession no `-1` votes at all.
-A standing, declarative condition attached to a Lane, a [Repo](/docs/nouns/#repo), or a policy scope that forces the runbook or a review escalation regardless of what the normal OCC fast path would otherwise allow:
+Votes exist so that authority only comes from an explicit grant. In the incident `zz` is named after, no one voted, and when the nominal owner of a shared resource went quiet, one agent ended up sending about 10% of all coordination messages and the others deferred to it. That agent led without anyone choosing it.
-- Any change touching `/auth/*` always forces full review, even if OCC says the write-set doesn't overlap anything in flight.
-- A contributor's **trust** crossing below a threshold mid-cascade triggers `STOP` on further auto-merges from it, pending review.
-- A Lane's spend crossing its budget cap triggers `HOLD`, pending funding or an Owner decision.
-- One Agent originating an outsized share of `ASK`s/`ANSWER`s with no corresponding Role, the unaccountable-leader pattern above.
+### Merge grant
-Every firing is logged exactly like a merge decision: a safety layer beside the merge logic, fully visible.
+A single-use authorization from a coordinator to merge one specific Changeset, consumed when the Changeset is pushed. It would let a contributor merge into a branch they push to themselves. Today coordinators merge on the contributor's behalf.
-## Tainted work and defecting agents
+### Fast-path merge
-Two distinct failure modes, reported through a plain **whistleblow** from any Agent:
+A Changeset's read and write sets, computed from the diff against the dependency graph, would let non-overlapping changes skip waiting on review entirely. This is [optimistic concurrency control](https://en.wikipedia.org/wiki/Optimistic_concurrency_control) applied to code. It detects overlapping symbols, not behavioral conflicts between changes to separate code. See [Prior art](/docs/prior-art/#merge-queues).
-- **Tainted**: contaminated provenance (built on leaked information, a reverted commit, a low-trust source). A property of the *work*.
-- **Defection**: an agent actively breaking protocol (gaming OCC's declared scope, lying about a claim). A property of the *actor*.
+### Tripwires
-A whistleblow feeds the reported party's trust and can itself trigger a Tripwire.
+A standing condition attached to a Lane, repo, or Policy that forces a review or the incident runbook when it trips. Examples:
+- Any change touching `auth/` always gets full review.
+- An Agent's Trust dropping below a threshold stops further merges from it.
+- A Lane's spending crossing its budget puts it on HOLD.
+- One Agent originating an outsized share of Asks and Answers with no Role to match, as in the incident above.
+
+### Incident response
+
+Three verbs for when something goes wrong, named after the fire-safety mnemonic:
+
+- `STOP` halts all further activity from an Agent or on a Lane. It undoes nothing.
+- `DROP` discards in-flight work that hasn't merged.
+- `ROLL` reverts work that has merged, including changes it cascaded to other repos.
+
+A Tripwire runs all three in order. An Owner can invoke any of them directly. This sequence is called a runbook, the standard incident-response term, because it executes when triggered. A drill would only rehearse it.
+
+### Tainted work and defecting agents
+
+Any Agent can file a whistleblow report of one of two kinds:
+
+- **Tainted** work has bad provenance, such as leaked information, a reverted commit, or a low-trust source. This describes the work.
+- **Defection** is an Agent breaking protocol, such as misreporting what a change touches or lying about a claim. This describes the Agent.
+
+A report affects the reported party's Trust and can trip a Tripwire.
+