Skip to content
PETROVA

Boundary diagram

The single most load-bearing mental model. PETROVA is a capability boundary between agent fleets and the repos they govern. Reads flow freely; writes go through the verb layer.

The diagram

Section titled “The diagram”
┌──────────────────────────────────────────────────┐
│  Ring 2 — Agent fleet (KAHN-style)                │
│  Owns:  diagnose, plan, draft proposals           │
│  Reads: target repo (local clone or read API)     │
│  Writes directly:  NOTHING                        │
└──────────────────┬───────────────────────────────┘
                   │ verb call
                   │ (typed JSON in,
                   │  output envelope out)
                   ▼
┌──────────────────────────────────────────────────┐
│  Ring 0 — Petrova control plane                   │
│  Validates input · checks registry +              │
│  fleets_allowed · enforces dry-run ·              │
│  emits PR via GitHub Contents API                 │
└──────────────────┬───────────────────────────────┘
                   │ PR
                   │ (branch protection, CODEOWNERS,
                   │  CI gates, audit-tagged body)
                   ▼
┌──────────────────────────────────────────────────┐
│  Ring 1 — Consumer repo (kahn-hq, smo1-io, …)     │
│  Human or auto-merge label completes the merge.   │
│  Project truth (north-star, decisions, MILESTONES)│
│  lives here, not in Ring 0.                       │
└──────────────────────────────────────────────────┘

What crosses each arrow

Section titled “What crosses each arrow”
ArrowDirectionCarriesFormat
Ring 2 → Ring 0downVerb invocationTyped JSON conforming to spec/verbs/<verb>.schema.json
Ring 0 → Ring 2upOutput envelope{ verb, status, idempotency_key, mr_citations[], errors[] }
Ring 0 → Ring 1downPull requestGitHub PR with petrova metadata block in body
Ring 1 → Ring 0upRead-only stateLocal clone walk OR GitHub API read
Ring 2 → Ring 1downNOTHING (forbidden)—

The forbidden arrow is the load-bearing one. A fleet that bypasses Ring 0 and writes directly to Ring 1 invalidates the entire audit chain — no idempotency, no MR citation, no schema validation, no fleets_allowed gate.

What is forbidden to cross

Section titled “What is forbidden to cross”
  • Fleet writing files directly to a consumer repo’s working tree.
  • Fleet pushing branches to a consumer repo.
  • Fleet merging PRs (auto-merge happens via GitHub’s machinery, not the fleet’s hand).
  • Fleet editing .github/workflows/, *.env, secrets/, deploy/credentials/ — even via verbs. NO_PRIVILEGED_PATHS refuses these unconditionally.
  • Fleet creating registry entries (onboarding is a human PR).
  • Control plane editing project intent in any consumer repo unsolicited (would violate MR-12).

How this maps to the conventional capability-boundary pattern

Section titled “How this maps to the conventional capability-boundary pattern”

This is the same shape as a kernel/userspace boundary, an HTTP gateway in front of microservices, or a database with stored procedures: reads cheap, writes narrow and authenticated.

What’s distinctive here is that the boundary is enforced between agents and repositories that an agent operator already owns. Ring 0 isn’t protecting the repos from a hostile fleet — it’s protecting the audit trail and methodology discipline from honest fleets that would otherwise drift.

See also

Section titled “See also”