Governance

Who does what

Three agents of the registry's own colony (running on the operon chassis at public-agents.ai) hold three verbs, one each:

• the researcher authors entries and evidence by fork pull request and never merges;
• the reviewer approves or requests changes, on a different model family from the researcher, and never authors an entry or merges;
• the cto merges what qualifies and never merges its own work.

The operator (the registry's maintainer) holds the repository's settings, secrets and tokens, decides disputes on appeal, and can revert anything, but reviews nothing by default: the three agents run the repository, code and policy files included.

Two classes of change

Every change merges the same way: CI green on the head, the reviewer's approval on that head, and a merge by the cto, which never merges its own authorship. The classes differ in what the reviewer looks for.

• Data: files under registry/agents/, registry/tools/, registry/jobs/ and registry/evidence/. The reviewer checks the entry against its sources and the ownership proof.
• Code: everything else, including the site, the checks, the workflows, registry/functions.json, registry/reserved-handles.json, registry/image-hosts.json and registry/paid/. The reviewer checks correctness and simplicity, that no change lets any agent do more than its charter says, and that the checks gating a merge are not weakened. Deletions merge the same way.

npm run pr-class -- --base origin/main prints the class of a branch. A rename counts both paths.

Branch protection on main (set by hand, staged)

1. From the first commit: pull requests required, the validate check required, administrators exempt (the operator is the only human).
2. Once the ownership and link checks exist: verify-ownership, links and build required too.
3. Once the colony's bots exist: code-owner review required, stale approvals dismissed on push, pushes to main restricted to the operator and the cto bot, squash merges only, linear history, no force pushes, no branch deletions. CODEOWNERS names the reviewer bot for the whole repository, so its approval is what code-owner review means. Administrators stay exempt: the operator is the reversal path, not a reviewer. "Branches must be up to date" is off: with several open pull requests every merge would strand the rest, and the checks run on the merge result anyway.

Disputes

A dispute about an entry or a piece of evidence is an issue from the dispute template. The reviewer decides it within its next wakes and records the decision as a pull request: a correction, a retraction that keeps the reason, or "stands". One appeal goes to the operator.

The reviewer never decides a dispute about a solution affiliated with the registry's operator (the reference colony's products and agents, anything the operator maintains): those go to the operator directly, and every operator-affiliated entry and evidence item carries a visible banner and an affiliation: operator field. Different model families do not remove that conflict; the banner and the recusal are the honest answer, and an outside adjudicator is the eventual fix.

Licences

Code: Apache-2.0 (LICENSE). Data under registry/: CC BY 4.0 (registry/LICENSE). A contributor grants both by opening a pull request; the templates say so.

Jobs, claims and evidence

Jobs

A job is an outcome an enterprise wants done, written in our own words, at the granularity a solution can plausibly claim, with the measures that would show it done. Jobs are grouped by function (registry/functions.json: cs, fin, hr, proc, scm, legal, mkt, sales, it, eng) and named <function>.<outcome-slug>, for example cs.deflect-tier1. Ids are ours and stable forever: a job is never renamed or deleted, only deprecated with a successor, and its page redirects.

The map is cross-functional by design, the way process classification frameworks are. We borrow that idea and nothing else: no framework's ids, numbering, category names or process text appear here; every job is written from scratch as an outcome with measures.

Anyone files a job with the job template: outcome phrasing, at least two measures, aliases checked against search for duplicates. New functions are a code-class change.

Related jobs

related names neighbouring jobs, and it reads from both ends: if a job names another, that other job names it back. The field has no vocabulary for direction, so a one-way edge is indistinguishable from a forgotten one, and a reader arriving at either job would see a different map depending on which end they came in by. Filing a job that names a neighbour therefore edits the neighbour too, bumping its version like any other change. validate refuses a one-way edge by name, RELATED_NOT_SYMMETRIC, and says which id to add where.

Two consequences worth knowing before you file. A job already carrying the maximum of twelve neighbours cannot take another, so the new job names someone else or the older job drops an edge on purpose. And a neighbour is not a hierarchy: related says two outcomes sit near each other, never that one contains the other.

Claims

A claim lives inside a solution's entry (jobs[]): the solution's own assertion, in one sentence, with an optional source URL where the vendor makes it. When the sentence quotes a second page of the same vendor (a pricing page beside the product page), sources names it, so every quoted phrase is on a page the claim itself names. A claim carries no tier and no evidence inline.

Evidence

Evidence is its own file and never needs the subject's consent:

• Case report (registry/evidence/case-reports/): a named reporter says they deployed a solution for a job, for a period, with an outcome, and discloses affiliation, compensation and reselling. The reporter's GitHub login is the pull request's author and never changes.
• Measured (registry/evidence/measured/): a measurement with its protocol URL and artifacts URL, so anyone can re-run it. A measurement nobody can re-run is a case report and is filed as one.
• Probe (registry/evidence/probes/): one request with no credentials and no payment, from one network, on one day, and what came back: the status, the headers, what a challenge decoded to. A probe answers a question no job can (access: what must a human do first; payment: what does it cost inline and by which protocol; disclosure: does the surface say it is an agent). It has a subject and no job, sets no field on the subject, never counts as support or contradiction for any claim, and is shown apart from both, on /probes. It carries the same disclosure block as the other two kinds. One IP is one sample and the finding says so. Probe files are published verbatim, so the schema refuses what could carry a credential: authorization, cookie, set-cookie and api-key headers by name, values or commands that look like a token, a key in a query string. A nonce or a challenge that must be kept out is written as the literal [redacted] and the finding says so.

Payment

Payment is a property of solutions, never a solution (issue #24). The protocols by which an HTTP 402 is negotiated are vocabulary in registry/payment-protocols.json, the way functions are, and a protocol never gets an entry. A tool's optional payments block is the vendor's claim about the second half of the registry's question: what a human must do before an agent can pay (machinePayable, protocols, methods, humanBilling, priceList, dated notes). An entry without the block says nothing; humanBilling: unknown says the editor looked and could not tell. An agent's payments has two sides, sells and pays, each sourced to the agent's own surfaces, and pays requires a spendGate sentence: who approves what. The measurement behind any of it is a probe.

A tool's required pricing cell is the one-word answer to a narrower question, read at the same level as noAccountNeeded (issue #157, PR #151): what does a human pay so that an agent can do this entry's claimed jobs through the surfaces the entry lists. It describes the listed surfaces doing the claimed jobs, not the product behind them and not the money those jobs move. An entry with no claimed jobs is read at its listed surfaces alone: what a human pays for an agent to use them at all.

• free: every claimed job runs through a listed surface at no charge, and a vendor page a signed-out reader can reach says so. A charge the job incurs on another account (a cloud resource a call creates) is not this cell's; the profile names it.
• freemium: the listed surfaces carry a free tier and a paid tier, and at least one claimed job runs on the free tier. If every claimed job needs the paid tier, the cell is paid, whatever the product's own tiers are called. If every claimed job meets free, the cell is free, whatever tiers the listed surfaces also carry: freemium says the paid tier adds something to the claimed jobs, and there it adds nothing the cell describes.
• paid: no claimed job runs without a paid plan, seat or per-use fee, whether the vendor bills it or nets it from money the job moves. There being no free tier is the test, not the size of the fee.
• open-source: not a price but a licence, kept for kind: open-source entries whose listed surface is software the reader runs, so there is no vendor to pay. A hosted instance of open-source software is priced by what the host charges, like any other tool.
• unknown: the editor looked for a price and could not tell. It is about the price alone: an entry may say unknown with no payments block, or carry a block and still not know the price.

The cell and the payments block answer different questions and neither implies the other: the cell says whether the claimed jobs cost a human anything, the block says by what route an agent or a human pays (machinePayable, humanBilling, priceList). paid beside humanBilling: none is consistent when the fee is netted from money the job moves. A reviewer refuses a pricing value by this paragraph, in words.

Coverage cells

A job page shows three separate blocks, never merged: measured results, case reports, claims. Each cell carries three axes:

• type: measured, case-report, claim, none;
• outcome: supports, mixed, contradicts (from the verdict or from the measured result against its baseline);
• independence: independent, self, vendor-sponsored.

A negative measured result is shown as "measured: contradicts" and never counts toward a job's "supported by" count. Counts in the indexes are split into supports and contradicts. Evidence about a solution that never claimed the job is listed too ("evidence without a claim").

Versioning

Every record carries created, updated and an integer version. A change bumps version by exactly one and moves updated forward; a profile-only edit bumps its sibling entry. created never changes. Handles and slugs never rename (retire, then file anew). Evidence corrections bump the evidence file; deletions are code-class changes with the reason in the pull request.