Merge policies and reviews

Reviewing every agent’s diff works for ten changes a day and breaks at ten thousand. A merge policy changes what a person approves: you approve the rules once, and review only the merges that break them.

#How it works

MERGE WORLD w  ├─ may the agent merge w at all? (merge_own or merge; write_main for main) ── no ──> refused  └─ inside the merge, holding its locks, on the exact rows it is about to apply:       does the agent keep to a merge policy?         no  ─────────────────────────────────────────> merged         yes: every rule kept? ── yes ────────────────> merged                               └─ no ──> refused (42501), every broken rule named;                                         the world stays, queued in Reviews                                           a person: read it, then Merge (at the version read) or Discard

• What’s checked is what merges. The rules run inside the merge, on the rows it applies, under its locks: nothing written a moment before or after can slip past.
• Stale work doesn’t win. A merge that would overwrite rows main changed since the fork needs a person, unless the policy allows overwrite.
• The queue says when it’s out of date. Each held world records its version when the agent asked; changed_since says the agent wrote more after.
• A policy only takes rights away. An agent needs merge_own to merge at all; the policy decides which merges need a person. An agent keeping to a policy changes main only by merging: a direct write, RESTORE or UNDO there is refused, since it would skip the rules.

#Start here: no delete lands on its own

Whatever else a policy says, start every agent with max_deletes = 0. A wrong update leaves a row you can see and fix; a wrong delete leaves nothing to look at. Most agents rarely delete, so the queue stays short, and each delete that comes through shows you whether to trust the agent with more.

create merge policy agents with (max_deletes = 0);alter agent "claude-ada-shop" set (policy = 'agents');

#The rules

Every rule is optional. A rule left out limits nothing, except schema, overwrite and critical, which start on the safe side.

• Counting: one per row the merge inserts, updates or deletes in the parent, after ONLY TABLES/ONLY KEYS. A row settled USING THEIRS changes nothing and doesn’t count; indexes, constraints and counters never do.
• Names: read as SQL reads them: orders folds to lowercase, "Orders" quoted is another table.
• Hourly rules: a sliding hour of the agent’s own merges into main; merges between its worlds count when they reach main, and a person’s approval doesn’t count.
• Merge checks: a broken merge check is one more broken rule for an agent with a policy: its world is queued with the rows the check found.

#Give a policy to an agent

On Chronos Cloud each person’s coding agent is claude-<login>-<project> (SHOW AGENTS lists them; the Policies page shows who keeps to what). Make the policy, then give it:

create merge policy careful with (max_rows = 500, max_deletes = 0, review_tables = 'payments');alter agent "claude-ada-shop" set (policy = 'careful');show merge policies;

#The review queue

A held merge tells the agent why, and the agent stops and reports it (on a production project the answer carries the review’s link):

merging bot_bulk needs a person's review (merge policy careful: it changes 6 rows (at most 3)); it's queued (SHOW REVIEWS)

The dashboard’s Reviews lists held worlds, oldest first. In SQL, SHOW REVIEWS:

• Approve: Merge in the dashboard, or MERGE WORLD w AT VERSION n. It lands only if the world is still at the version you read.
• Approve part: MERGE WORLD w ONLY TABLES (orders) or ONLY KEYS (…); the rest stays queued.
• Reject: Discard, or DROP WORLD w.
• Email: owners and members are emailed when a world starts waiting (one email per version), unless they turn it off under Team → Notifications.

The agent can’t skip the queue: the hold is kept where only the database writes it, so the agent can’t clear it or merge the world until a person does, or until it fits the rules.

#Confirming big deletes

With confirm_deletes_over = 100, a merge deleting more than 100 rows waits, and the person approving must give the count, counted from the merge’s own plan:

merge world cleanup confirm deletes 4812;-- a missing or wrong count is refused (55000) with the real one, before anything is written

A dry run’s notice gives the CONFIRM DELETES n that approves it. An agent can’t give the count for its own merge.

#A reviewer before a person

Rules first, a reviewer model next, a person for what’s left. Name an agent as the policy’s reviewer; it reads each held merge and decides, with a reason:

alter merge policy careful set (reviewer = 'critic');-- as critic (or the MCP tools reviews, diff and review):review world bot_bulk approve reason 'a duplicate of lead 4';     -- merged, as it was heldreview world bot_refund reject reason 'lead 2 has an open deal'; -- not merged; a person sees whyreview world bot_odd pass reason 'not sure: check the deal';     -- left to a person

• Approve merges at the held version; a world written to since is refused (40001). A big delete under confirm_deletes_over still needs a person’s count.
• Reject and pass leave the world queued with the decision in its reviewer column. A person can overrule any decision.
• Decisions are in the audit trail: SHOW AUDIT FOR AGENT critic.

#Tuning and measuring

alter merge policy careful set (max_rows = 100);       -- the named rules change; the rest stayalter merge policy careful set (max_deletes = null);   -- null: no limitalter agent "claude-ada-shop" set (policy = null);     -- its rights alone decide nowshow merge outcomes;                                   -- how each agent's worlds endedshow merge outcomes by policy;

SHOW MERGE OUTCOMES counts, within the history window, how each agent’s worlds ended (merged on the rules alone, approved, rejected, discarded, still open) and how often merges were held, conflicted or refused. rules_rate is the share of decided worlds that merged on the rules alone: low means the rules hold too much; people undoing what passed means they hold too little.

Try rules before you set them

The MCP tool check_merge_policy runs rules against a world’s real changes and says whether its merge would land or wait, and why. Nothing is saved, so “what if max_rows were 1000?” is one call.

#Recipes

#From an agent