Governance model

This is the umbrella page. Every other concept page describes one mechanism; this one names the whole governance model and how the mechanisms compose. If you read only one page, read this — then follow the links into the mechanism you need.

The claim in one sentence: PETROVA can only change a governed repo by emitting a schema-validated, idempotency-keyed, meta-rule-citing pull request through a narrow verb surface, admitted by declarative gates in registry.yaml, and continuously audited against the meta-rules — with the human-merge boundary as the last gate.

The write path, end to end

%%{init: {'flowchart': {'htmlLabels': false, 'curve': 'linear', 'nodeSpacing': 45, 'rankSpacing': 55, 'padding': 12}}}%%
flowchart TD
    C([caller: CLI / skill / fleet])
    R{"registry gates
role · profile · fleets_allowed
contract_committers"}
    V["verb
schema-validate + constraint-check"]
    P{"phase-integrity
act-time guard"}
    D[/"dry-run
diff preview"/]
    A["apply
branch + Contents-API commit"]
    F{"MR-12 firewall
registry-edit verbs"}
    PR["PR (idempotency key + MR citations in body)"]
    M(["human merge
(or cosign opt-out)"])
    AU[["live MR audit
MR-1…MR-17"]]

    C --> R -->|admitted| V --> P -->|no hard regression| D
    P --> A
    D --> PR
    A --> F -->|"act.* verbs"| PR
    F -->|"registry-edit: default"| M
    PR --> M
    AU -.observes.- R

    classDef gate fill:#c8631f,stroke:#7a3a10,color:#fffaf2,font-weight:600;
    classDef peer fill:transparent,stroke-width:1px;
    class R,P,F,V gate;
    class C,D,A,PR,M,AU peer;

The primitives

Primitive	What it governs	Where it lives	Page
Verbs	The entire write surface — no other path changes a governed repo	`spec/verbs/*.schema.json`	Verbs
Registry	Which repos are governed at all	`registry.yaml` (schema: `registry.schema.json`)	Registry
Profile gate	Whether a fleet may `request_merge_when_green` or only `request_review`	`registry.yaml` `profile:`	Profiles
`fleets_allowed` gate	Which agent identities may invoke write verbs	`registry.yaml` `fleets_allowed:`	Fleets
`contract_committers` gate	Who may commit a consumer’s `.petrova/contract.yaml`	`registry.yaml` `contract_committers:`	Registry
`integrations_applicability`	Governance override of a consumer’s integration self-declaration	`registry.yaml` `integrations_applicability:`	Registry
Idempotency key	Re-run detection — the same input is a no-op	`_common.schema.json` `IdempotencyKey`	Idempotency keys
Dry-run default	No verb mutates unless explicitly applied	verb pipeline	Dry-run vs apply
Phase-integrity guard	Blocks a phase transition that would regress hard phase integrity	`host/src/tools/phase-guard.ts`	Phase integrity
Live MR audit	Continuous conformance to the meta-rules	`host/src/sources/audit.ts`	Governance audit
MR-12 firewall + cosign	Human-merge boundary on registry-edit verbs, with an authorised opt-out	`cli/src/cosign.ts`, `docs/runbooks/cosign-automerge.md`	Runbook

The verb surface, precisely

There are 18 control-plane verb schemas under spec/verbs/. They split three ways by exposure:

16 write verbs are exposed as petrova.act.* tools on the Fleet MCP host. Each opens a PR; none pushes directly. These are the governance-bearing surface.
diagnose is read-only — it surfaces findings, it does not write.
daedalus_distribute is CLI-only: it has a spec schema and a cli/src/verbs/ implementation and a ratifying decision doc (docs/decisions/2026-06-05-add-daedalus-distribute-verb.md), but is deliberately not exposed as a petrova.act.* Fleet MCP tool. Fleets cannot invoke it; an operator runs it from the CLI.

On the Fleet MCP host itself, this is 17 of 42 tools mutating: the 16 petrova.act.* verbs plus petrova.sweeps.trigger (a workflow_dispatch with no act. prefix). Downstream proxies enforcing a read-only surface must filter on the mutating flag, not the name prefix — see host/src/registry.ts.

Every verb carries the same envelope

Governance is legible because every verb — write or read — returns the same shape (_common.schema.json OutputEnvelope):

verb, target_repo
status — one of validated, dry_run, applied, skipped_idempotent, failed
idempotency_key — SHA256(verb|target_repo|canonical_input_json), 64 hex chars, embedded in the PR body so a re-run detects itself
mr_citations[] — the meta-rules this action upholds
errors[] — structured, never silent
triggered_by — required by MR-7: every action names what surfaced the need for it

The gates, in order

A verb only reaches apply if it clears, in sequence:

Registry admission. The target slug must exist in registry.yaml. Absent → invisible to the verb surface.
Identity (fleets_allowed). The actor must be a permitted fleet (or a human). Empty fleets_allowed: [] means human-only writes — this is how petrova-codes governs itself.
Contract authority (contract_committers). For verbs touching a consumer’s .petrova/contract.yaml, the committer must be allowlisted. Default ['humans']; adding a fleet is itself a governance change requiring a notes: justification.
Schema + constraints. Input validates against the verb schema before any side effect, even in --apply. Declared constraints (e.g. DEFERRED_HAS_TARGET) surface as structured errors.
Phase-integrity (write-time). start_phase / close_phase are blocked if the transition would introduce a hard phase-integrity finding absent from the current ledger (REPO_PHASE_INTEGRITY). The guard is fail-open — enforcement must never wedge governance.
Merge boundary (MR-12). The four registry-edit verbs (petrova_act_registry_edit, petrova_act_reconcile_drift, petrova_act_register_consumer, petrova_act_deregister_consumer) default to human-merge-only. The cosign path is the only authorised opt-out, and requires three independent gates to align.

Continuous audit

Gates decide admission; the live MR audit (host/src/sources/audit.ts) decides conformance, continuously. It evaluates governed repos against thirteen meta-rules at runtime — MR-1, 3, 4, 5, 7, 8, 10, 12, 13, 14, 15, 16, 17 — and renders each as a pass/fail row on the dashboard. Two are load-bearing for the model:

MR-13 / MR-14 keep intent (.petrova/contract.yaml) and observation (state/<slug>.yaml) apart: probes auto-demote, never auto-promote. Governance never quietly upgrades a repo’s claimed posture from a passing probe.
MR-16 audits verb wrappers against the spec catalogue, so the documented verb surface and the exposed one cannot silently diverge.

See Governance audit for how to read a failing row.

Why this shape

The narrowness is the product. A fixed verb catalogue, declarative admission gates, idempotent PRs, and a continuous meta-rule audit are what let the control plane stay thin, keep the audit trail legible, and never replace human judgement at a phase boundary — prompts surface and draft; the human signs off.