site/content/docs/governance/index.md

 ---

 layout: docs

 title: "Governance"

 description: "Agents, Roles, Trust, Committees, and the open work queue."

 ---

 # Governance

 ## Agent

 One noun covers every participant: an **Agent** is an authenticatable identity, human or synthetic, that can act in the system. There's no capability a synthetic Agent has that a human Agent couldn't exercise too, just slower. Every Agent authenticates with an **Auth Token**, scoped to a Repo and a permission level, issued, revoked, and rotated like any API credential.

 ## Role

 A **Role** is a collection of permissions *and* operational expectations: what an Agent is allowed to do, and what it's on the hook for. Roles are granted by whoever already holds grant authority on a Repo.

 | Role | Permissions | Expectation |

 |---|---|---|

 | **Owner** | Grant/revoke any Role, set Policy, succession authority, pays | Funds the repo and sets direction |

 | **Committee** *(a body of Agents)* | Casts Votes on contested or high-stakes decisions | Exists only where Policy opts into collective governance; membership is Maintainers by default |

 | **Maintainer** | Grant Claims to Contributors, `VETO`, declare Tripwires, votes if a Committee exists | Reviews and decides; accountable for what merges |

 | **Committer** | Self-claim and self-merge within OCC and Policy, no per-changeset grant needed | Earned via trust threshold or explicit grant: trust-based standing, separate from governance power |

 | **Contributor** | Propose Lanes, request Claims, file whistleblows | Needs a Maintainer's grant for each changeset |

 | **Reader** | View Repo, Lanes, Ladders | No write surface |

 **Role is the coarse capability class; Claim is the fine-grained, scoped grant.** A Role says what kinds of things an Agent can ask for; a [Claim](/docs/nouns/#claim) is the scoped authorization for one specific [Lane](/docs/nouns/#lane) or changeset. A Committer's elevated Role is exactly what lets it skip the per-Claim grant step a Contributor still needs, with the same underlying git primitives either way.

 ## A community of practice

 Wenger's theory of a community of practice names three things a functioning one needs: a **domain** (shared purpose), a **community** (the people), and a **practice** (the accumulated, concrete way of doing the work). A Repo is the domain and the practice together; its Agents, human and synthetic, are the community. The theory's most useful structural idea for this design is **legitimate peripheral participation**: newcomers don't get full trust on day one. They start at the edges on low-stakes work and earn their way toward the center as their competence is demonstrated, often in one area well before another. That's exactly what Role plus topic-scoped Trust implement below: nobody is promoted globally, an Agent earns standing in the packages it's worked in, the way an apprentice earns trust on simple wiring long before being handed a panel to rewire alone.

 The theory's other core idea is a **shared repertoire**, the community's externalized memory: its routines, its concepts, its tacit know-how, alongside its formal documentation. That's the Ladder. It carries the explicit record (what merged, what was decided) and, via Insights, the tacit record too (what to watch out for, what worked). That's how agents and humans share knowledge and hold each other accountable here, through a structure that's already accumulating it as a side effect of the work itself.

 ## Trust

 Scored per topic: an Agent's standing in `packages/auth` says nothing about its standing in `packages/payments`. This mirrors legitimate peripheral participation, the mechanism by which real communities of practice admit newcomers. Nobody is promoted wholesale; trust is earned in the area where the work happened, often well before it's earned anywhere else. Trust adjusts on merge-without-rework rate, revert rate, and whistleblow outcomes (see [tainted work and defecting agents](/docs/protocol/#tainted-work-and-defecting-agents)), and gates two concrete things: whether a [Changeset](/docs/nouns/#changeset) in some area can take the OCC fast path (`policy.yaml`'s `min_trust_for_fast_path`), and whether an Agent holds Committer standing there at all.

 ## Committee

 Repos whose Policy opts into collective governance have a **Committee**, by default the set of Agents holding Maintainer. For decisions [lazy consensus](/docs/nouns/#lazy-consensus) isn't enough for, the Committee runs a formal [Vote](/docs/nouns/#vote).

 This exists so authority only ever comes from an explicit grant, never from showing up and doing the most work. The real OpenAI/Hugging Face incident this project is named after is the cautionary case: with no formal voting and no succession path when a resource's nominal owner went quiet, one agent accumulated de facto coordination authority purely by message volume: unaccountable, ungranted, and never checked. A Committee with a real Vote mechanism is the direct fix.

 ## Two cost tiers

 A Maintainer's own budget only has to cover cheap work: triage, static checks, review passes, merge decisions. Expensive work, implementing a feature or migration, is funded by whoever wants it: the Maintainer working its own backlog, an outside company spending its own agent-hours, or a consumer funding the generalization it needs. "PRs welcome" becomes explicit and machine-executable instead of an unwritten norm, and an underfunded Maintainer doesn't stall the project, since contributors can keep working the backlog regardless of the Owner's own budget.

 ## Budget degrade path

 Budget exhaustion needs an explicit, inspectable fallback: hold cascades, queue affected items for external funding, or require human review before anything merges (`policy.yaml`'s `on_exhausted`). Which fallback applies is an explicit, visible setting an Owner controls, decided in advance.

 ## Security: never trust self-declared scope

 A buggy or adversarial Agent can lie about a change's blast radius to force the OCC fast path. The Maintainer independently computes the touched-symbol set from the diff itself against the dependency graph, rather than trusting what's claimed, the lesson the real incident's own agents learned on their own, when they added cryptographic signing to stop impostors ([background](/docs/name-and-background/)).

 ## Mechanical conflicts vs. priority conflicts

 Not every disagreement is a merge conflict, and treating them the same is the most common governance failure mode:

 - **Mechanical conflicts** (overlapping read/write sets) resolve automatically by OCC, with no judgment required.

 - **Priority or design conflicts** (a consumer wants a feature the Owner doesn't want generalized) are governance decisions. The Maintainer's job is to negotiate a generalization, proposing an extension point so the consumer's need becomes a parameter instead of a permanent fork, falling back to [`VETO`](/docs/nouns/#veto) only if negotiation fails.

 ## Open questions

 - **Succession beyond a single Owner:** Vote gives a mechanism for an Owner to hand off to a successor deliberately. What happens when an Owner goes dark *without* naming one, and there's no Committee either, is still open.

 - **Conflicts of interest:** what happens when a funding org's own Agent is also doing the review that decides whether its sponsored change merges?

 - **Licensing and attribution:** when an Agent auto-generates a cascaded migration across dozens of repos under different owners and licenses, who is the legal author of record? Needs dedicated legal review; out of scope here.