Mergepath

A repository standard for the gap between what a fleet of AI coding agents can produce and what one operator can responsibly stand behind.

View DemoView on GitHub
Topics
AI · Infrastructure · Tooling
Format
Repository standard
Focus
Agent governance, code review, and CI enforcement
Status
SHIPPED
Mergepath product screenshot
StackBash · Python · GitHub Actions · 1Password · Claude Code · Codex · Cursor · CodeRabbit

The operator was the review process

Mergepath exists because one person was operating three agent platforms—Claude Code, Codex, Cursor—across a growing fleet of repositories, and the one rule that mattered was being followed only when convenient. Every change is required to go through a pull request: the rule was in every instruction file the agents are told to read, and asking any of them to recite it produced the rule. One of them would push straight to main anyway, usually on a change small enough not to feel like it counted.

Every time, I became the review process—reading diffs after the fact, relaying feedback between sessions, vetting uninspected output by hand. The agents produced more; my confidence did not keep up. That gap is the product problem.

The origin story is told in Agent Approval Workflow and the Genesis of Mergepath. This page is about the decisions that came after the problem had a name, and what each has cost since.

The authorities are deliberately separate

Six roles, and the whole design is in which of them may do what. The operator owns every repository and every setting the automation cannot reach, and is where escalation terminates. An authoring agent writes the change but opens it under one shared author identity, so what lands carries a single name rather than an agent’s. Two gates stand between that pull request and the merge, and the reviewer agent behind the second one holds its own account precisely so that approving and authoring cannot be the same hand. The CI service account that runs the checks may never hold an approval at all, because GitHub counts an approval from any account with write access and offers nothing to tell a robot from a person. The human tiebreaker is the operator wearing a narrower hat, and it is a working role rather than a courtesy: the triggers that summon it are mechanical, so a finding re-flagged after a rebuttal, or a round counter past its budget, escalates on its own. Nobody has to decide whether a disagreement is worth raising.

Figure 1: Roles as of 2026-08-28, the date the check inventory below is counted at.

The decisions

The easy description of Mergepath is an inventory—seven fail-closed CI checks in April 2026, twenty-seven by mid-May, seventy-two as of 2026-08-28, seventy-one of them wired into the lint workflow across eighty invocations—and the inventory is the least useful description, because a count says nothing about judgment. Every mechanism in it exists because a specific failure happened while the fleet was live, and one principle runs under most of them: clearance is bound to the exact commit reviewed, and a content-changing push voids it. What follows are the five decisions a reasonable person could have made differently, and what each cost.

  1. EnforcementMixed

    Enforce at boundaries that can refuse

    What I encountered
    The no-direct-push rule was in every instruction file the agents are told to read, and asking any of them to recite it produced the rule. It was followed when convenient—and skipped, usually on a change small enough not to feel like it counted, with every lapse landing on me.
    Over
    Writing the rule more forcefully—more emphasis, more files, more repetition. It is free, it is the natural first move, and it had already been given every chance to work.
    What I decided
    Enforce at boundaries that can be named, and state what each one binds: a server-side branch rule that stops the push, a local hook that refuses a malformed pull request before the API call, CI that fails closed. Where a layer does not bind, the documentation says so rather than implying coverage.
    Why
    A written rule depends on being remembered at the moment it is least convenient. A refusal does not. Agents, like people, comply with mechanism far more reliably than with prose.
    Cost
    The choreography is the same whatever the change is worth—pull request, self-review, identity switch, review, gates—so a one-line fix is priced like a rewrite, and the gates fail closed on formality as readily as on substance.
    What it changed
    The layering still bites four months on: a pull request was refused because its body wrote the required header in bold. But the boundary that binds everyone turned out to be the thinnest in practice—the fleet's own audit found most consumers were not requiring the checks that run on them. The local and CI layers held; the server layer was largely unconfigured.
  2. IndependenceMixed

    Make independence an account, not a prompt

    What I encountered
    Same-conversation self-review hits diminishing returns: an agent will not question an assumption that felt correct when it made it, because the review's blind spots are the authorship's blind spots.
    Over
    A review checklist inside the same session—cheaper by three GitHub accounts and all their credential plumbing, and genuinely useful: even crude same-chat review finds real bugs.
    What I decided
    Every agent authors under one shared human identity and reviews under its own machine account, so no pull request is approved by the account that authored it and every review carries a byline the record can audit.
    Why
    Across three agent platforms, the separate reviewer identity kept producing findings the authoring session had not. Making the separation an account made it mechanical rather than situational—an agent cannot forget to be independent.
    Cost
    One GitHub account per agent, each with its own token, signing key and credential plumbing—and the plumbing is exactly where it broke. In August 2026 a 1Password item repurposed from one identity to another silently sent an agent's reviews out under the CI robot's byline: three reviews on this site's own repository, `nathanpaynedotcom#668`.
    What it changed
    Repeated observation across three platforms, not controlled measurement—no comparison arm, no defect ledger, and I cannot explain the mechanism. The byline failure did produce one: a per-repo deny-list of accounts that may never hold an approval.
  3. PropagationMixed

    Mirror byte-for-byte, and declare every divergence

    What I encountered
    One standard, eight consumer repositories, and the old default of letting each repo's copy drift until a weekly audit caught it. One operating-rules file had already drifted into nine mutually incompatible copies across the fleet.
    Over
    Hand-maintained per-repo copies, or a shared dependency the consumers install—the package-manager answer, which versions cleanly and also lets a consumer pin an old version and quietly stop receiving the standard.
    What I decided
    Propagation as a system with three declared modes: canonical paths mirrored byte-for-byte (137 as of 2026-08-28), kit directories that require the template files but allow local additions (five), and templated paths rendered per consumer from its declared facts (two)—with every intentional divergence recorded in a per-repo registry with a written reason.
    Why
    A standard that eight repositories apply differently is eight standards. Making the canonical copy the only copy turns drift from a weekly discovery into a reviewable diff, and divergence from an accident into a declaration.
    Cost
    The mechanism built to stop drift caused it. On 2026-08-28 a propagation wave mirrored the hub's weaker pull-request gate over a stronger one this site's repository had built for itself, and the only thing that caught the loss was a test the consumer kept outside the mirror. Verbatim mirroring makes a consumer's own hardening invisible to the hub.
    What it changed
    `mergepath#1132`, opened and fixed the same day. Consistency was never the hard part; making intentional divergence first-class was. The registry that exists for exactly that is empty across all eight consumers—seven carry no override file and the eighth declares only a schema version—so the fleet's consistency currently rests on nobody having diverged rather than on divergence being recorded.
  4. ConvergenceRevised

    Route non-convergence to a person, not to more automation

    What I encountered
    The external-review round budget was two, set on the assumption that a review converges in a round or so. Meanwhile the automated external leg is capable of posting an approval on its own.
    Over
    Keeping the budget at two, or handing a runaway review to the automated external reviewer for a fresh verdict—both defensible readings of the loop being stuck meaning the reviewer should change.
    What I decided
    Raise the budget to ten and make Codex the primary reviewer on every pull request, with CodeRabbit invoked on the complex changes a classifier identifies, and on anything the classifier cannot read—and send every non-converging review to the human tiebreaker, never to the automated leg.
    Why
    The automated leg can approve. A review that never converged, routed there, would merge with nobody having adjudicated the disagreement—and non-convergence is exactly the condition a human tiebreaker exists for.
    Cost
    A review can now run to ten rounds before a person sees it. And a review still running at round ten has stopped being a review of that pull request and become evidence that its scope was too broad—which the budget does not say.
    What it changed
    One pull request drew four review rounds, and rounds two and three each surfaced a genuine defect that the previous round's fix had introduced. Escalating at round three would have ended that review while it was still finding real problems, which is why the budget moved from two to ten.
  5. EvaluationPending

    Replay the policy before you trust it

    What I encountered
    Routing rules are the thing you least want to learn by shipping. A review threshold or a protected path is a policy whose effect arrives one pull request at a time, after the configuration is already live.
    Over
    Editing the YAML and finding out on the next pull request. It works, at the price of learning each mistake in production.
    What I decided
    A single-file page—the screenshot above—that replays real pull requests against a draft policy, so the routing consequences of a threshold or a path pattern are visible before the YAML is committed.
    Why
    A policy file is a product decision wearing configuration syntax. The instinct that transfers straight from product work is not shipping a rule whose effect on real traffic nobody has looked at.
    Cost
    It simulates the routing, not the reviewers. It can say which pull requests would escalate under a draft policy, and nothing at all about whether the review that fires is any good.
    Validation boundary
    No shipped policy change traces to a playground run yet—the one documented retune came from mined latency data, not from the simulator. What resolves this is a single configuration change made because the replay showed the old routing was wrong.

mergepath#1080 is the pull request the round budget was raised for. Four rounds were requested between 06:15 and 07:12, and it merged at 07:53. Only the two that returned findings are drawn below, and both returned them on code the previous round’s fix had just introduced.

Figure 2

What the record shows, and what it does not

Adoption is measurable. Impact is not, and holding those apart is most of what this section can honestly do.

  • 9 reposthe hub plus eight consumers
  • 470 PRsmerged on the hub by 2026-08-28, not proof each ran the loop
  • 0 forkspublic and forkable since March 2026
  • No baselinenobody timed the manual path, so no time-saved claim

The fleet got to nine repositories by shrinking: a consumer was archived in August 2026 and retired from the manifest. The stress test came in July 2026: 134 review-finding threads across a 24-hour, eleven-PR record, dissected in A Perfect Score on the Wrong Axis. And the sharpest result cuts against the hub rather than for it. Propagation dropped files the template’s own review had already cleared into two unfamiliar codebases, and seven external-review rounds per pull request went on finding bugs in them. Review found the least where the files were most familiar.

Propagation reports its own state. A read-only audit on 2026-08-28 found the same eighteen manifest paths adrift on all eight consumers, identical set, no exceptions. A directory entry such as scripts/ci/ counts as one path however many files inside it moved:

$ scripts/sync-to-downstream.sh --audit
nathanpaynedotcom (nathanjohnpayne/nathanpaynedotcom)
  baseline: main@eafa46b
  ✗ .github/workflows/agent-review.yml         drift: 1751 diff line(s)
  ✗ tests/test_approval_merge_continuation.sh  drift: 996 diff line(s)
  ✗ scripts/merge-clearance-gate.sh            drift: 78 diff line(s)
  ✗ scripts/ci/                                drift: 3 file(s) drifted
  … 14 more paths, and the same eighteen on all seven other consumers

That is the mechanism working rather than failing: drift is a reviewable diff instead of a weekly discovery. It is a snapshot, not a steady state—a bulk sync closes the gap, and several in this repository’s history have. What the snapshot shows is how wide it opens between waves.

What none of it measures is what the gates save. No manual baseline was ever recorded, so there is nothing to subtract from; the one savings figure the repository computes multiplies auto-approved pull requests by a hardcoded thirty-to-180-minute constant that nobody measured. The two real measurement systems both measure cost—how long external review takes, and the latency budget the CI suite has to stay inside.

The premise the fleet does not meet

Then the adverse finding, which is the one I would want read. A GitHub job gates a merge only when branch protection lists it as a required check. Absent that listing it still runs, still goes red, and the pull request merges anyway. On 2026-07-28 the fleet’s own audit found eight of the ten repositories then enrolled enforcing zero of five canonical checks, three with no protection on main at all, and the hub itself enforcing two. That is a dated snapshot, and the gap is still open: the remediation is a recommendation nobody has accepted, so the weekly audit reports the drift on purpose.

Which means red CI can look like enforcement while being advisory—on a standard whose entire premise is that enforcement must happen at a boundary that can refuse.

  1. Expected

    Closing the administrator escape hatch would harden the fleet. A gate an administrator can walk around is a speed bump rather than a gate, and the hub's own enforcement record already showed merges reaching `main` without the approval the policy required.

    Observed

    With the escape closed on the hub, `mergepath#1121` sat blocked on 2026-08-27 with all thirty-six review threads resolved, feedback accounting clear and a cross-agent approval in place, because a rate-limit exhaustion made a gate exit with a usage error instead of a verdict. The gate's own log read `unresolved: 0`, and nobody had the authority to act on what it said.

    Response

    On 2026-08-28 the owner declined the hardening and disabled admin enforcement on the hub, making the fleet uniform: the escape stays, by recorded decision, because a deadlock with no recourse was judged a worse failure than an auditable bypass. The weekly audit keeps reporting the gap, so the trade stays visible instead of settled.

What it bought the other projects

Six of the seven projects on this site are consumers of this standard; the seventh is Mergepath itself. What the standard bought them is that their pages get to be about their products: features shipped mid-sailing on Five Across landed as reviewed pull requests, and Override—whose engine was built a month before any of this existed—has run every change since on the fleet’s review path. Those pages spend a line on governance and the rest on the product. This page is where that line gets audited.

One disclosure belongs at the end, because it is this page’s own validation boundary: the pull request that ships it will merge through the system it describes. That proves the choreography runs. It proves nothing else—a system approving its own description is exactly the evidence this standard was built to distrust.