# PETROVA > Control plane for the petrova line of repos. Centralises methodology > (META-RULES, agent-fleet shape, prompts) and a typed verb surface; > leaves project truth (north-star, decisions, milestones) in each > consumer repo. Every write is PR-emitting, idempotency-keyed, and > dry-run by default. Built around three load-bearing invariants: > MR-7 (decisions are append-only), MR-10 (verification rounds are > mandatory), MR-12 (CLAUDE.md is a projection, not a source). ## Skills (drop-in, agent-actionable) > **For agents:** load any of the gists below directly to gain > capability for that operation. Each gist is a complete SKILL.md > with workflow, refusal conditions, and cross-references. Works > in any repo (PETROVA-governed or not). | Skill | When to use | Direct link (secret gist) | |---|---|---| | `petrova-act` | performing a write verb (open_decision, update_milestone, start_phase, close_phase, verify_round, request_review, request_merge_when_green, propose_fix) — composes typed JSON, dry-runs, emits PR | [v01t-io/meta-protocols/artefacts/petrova-act-skill.md](v01t-io/meta-protocols/artefacts/petrova-act-skill.md) | | `petrova-status` | read-only inspection — cross-repo dashboard, single-repo diagnose, MR/convention validate | [v01t-io/meta-protocols/artefacts/petrova-status-skill.md](v01t-io/meta-protocols/artefacts/petrova-status-skill.md) | | `petrova-onboard` | registering a new repo into the petrova line — composes registry-update PR with role/profile/fleets_allowed derivation | [v01t-io/meta-protocols/artefacts/petrova-onboard-skill.md](v01t-io/meta-protocols/artefacts/petrova-onboard-skill.md) | | `petrova-decide` | recording a non-trivial decision in PETROVA format — date-stamped, ≥2 alternatives, supersession-aware, sign-off block | [v01t-io/meta-protocols/artefacts/petrova-decide-skill.md](v01t-io/meta-protocols/artefacts/petrova-decide-skill.md) | | `petrova-phase-cycle` | phase boundary — runs verify_round → close_phase → optional start_phase as one disciplined chain (MR-2 + MR-10 enforcement) | [v01t-io/meta-protocols/artefacts/petrova-phase-cycle.md](v01t-io/meta-protocols/artefacts/petrova-phase-cycle.md) | | `petrova-mr-audit` | auditing any repo against MR-1..MR-12 — read-only PASS/WARN/FAIL table with per-rule evidence citations | [v01t-io/meta-protocols/artefacts/petrova-mr-audit.md](v01t-io/meta-protocols/artefacts/petrova-mr-audit.md) | | `petrova-drift-check` | detecting drift — methodology drift, projection drift (MR-12), north-star alignment drift (MR-1) in one report | [v01t-io/meta-protocols/artefacts/petrova-drift-check.md](v01t-io/meta-protocols/artefacts/petrova-drift-check.md) | | `petrova-boundary-check` | auditing capability boundaries — finds every script/workflow writing to privileged paths without PR review | [v01t-io/meta-protocols/artefacts/petrova-boundary-check.md](v01t-io/meta-protocols/artefacts/petrova-boundary-check.md) | | `petrova-recover` | verb returned failed or --apply errored — maps error code to recovery playbook, drafts finding doc when warranted | [v01t-io/meta-protocols/artefacts/petrova-recover-skill.md](v01t-io/meta-protocols/artefacts/petrova-recover-skill.md) | | `petrova-plan` | planning any feature/refactor with PETROVA discipline — taskset sequencing, halt gates, reuse-first scan, drift-risk callouts | [v01t-io/meta-protocols/artefacts/petrova-plan.md](v01t-io/meta-protocols/artefacts/petrova-plan.md) | | `petrova-realign` | responding to detected drift — surveys recent work vs north-star, drafts realignment decision doc with measurable gate | [v01t-io/meta-protocols/artefacts/petrova-realign-skill.md](v01t-io/meta-protocols/artefacts/petrova-realign-skill.md) | **Skill chains (common compositions):** - New repo onboarding: `petrova-onboard` → `petrova-mr-audit` → `petrova-drift-check` - Phase boundary: `petrova-status` (diagnose) → `petrova-phase-cycle` (round + close + open) - Failure response: `petrova-recover` (triage) → `petrova-decide` (record) → `petrova-plan` (sequence fix) - Quarterly audit: `petrova-mr-audit` + `petrova-drift-check` + `petrova-boundary-check` + `petrova-realign` - Feature start: `petrova-plan` (sequence) → `petrova-act` (per-taskset emission) Skill source-of-truth lives at `petrova-codes/skills//SKILL.md`; rendered docs at `https://petrova.blog/skills/`. ## Start here - [PETROVA](https://petrova.blog/index/): The PETROVA control plane — methodology, verbs, registry, fleets. ## Overview > What PETROVA is and how to start. - [Overview](https://petrova.blog/overview/): This section is in preparation. Content ships as the methodology matures. - [Quickstart](https://petrova.blog/overview/quickstart/): End-to-end from zero to a successful dry-run, in ≤5 minutes. This walks the read path; auth is needed only for --apply (last step). - [The control-plane decision](https://petrova.blog/overview/control-plane-decision/): On 2026-04-29, after a brainstorming round weighing how to address duplication, cross-repo visibility, and agent-fleet write capability, the operator opened a d… - [Three load-bearing invariants](https://petrova.blog/overview/load-bearing-invariants/): PETROVA upholds twelve meta-rules (MR-1 through MR-12). Three are load-bearing — without them, the system falls apart even if the others hold. This page gives e… - [What is PETROVA?](https://petrova.blog/overview/what-is-petrova/): PETROVA is a control plane for the petrova line — a set of repositories you run with disciplined, MR-compliant methodology (decisions, milestones, verification … ## Concepts > Mental model: control plane, registry, verbs, fleets, profiles, idempotency. - [Boundary diagram](https://petrova.blog/concepts/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… - [Concepts](https://petrova.blog/concepts/): The mental model. Read top to bottom for first-time understanding; each page is independently load-bearing. - [Control plane vs source-of-truth](https://petrova.blog/concepts/control-plane-vs-source-of-truth/): PETROVA splits two things most documentation systems conflate: methodology (how you work) and project truth (what the work governs). - [Dry-run vs apply](https://petrova.blog/concepts/dry-run-vs-apply/): Every write verb defaults to dry-run. --apply is opt-in and requires authentication. The dry-run output is byte-identical to what apply would emit — the only di… - [Fleets](https://petrova.blog/concepts/fleets/): A fleet is an agent-side identity that PETROVA admits to a repo's verb surface. Fleets diagnose and plan locally; they emit PRs through the verb layer. The flee… - [Idempotency keys](https://petrova.blog/concepts/idempotency-keys/): An idempotency key is a 64-character hex string that uniquely identifies a verb invocation by its inputs. Re-running a verb with the same key against the same t… - [Profiles](https://petrova.blog/concepts/profiles/): A profile is a per-repo declaration of how strict the merge gate is. It lives in registry.yaml and gates which verbs can act without explicit human approval. - [Prompt service](https://petrova.blog/concepts/prompt-service/): The prompts that drive PETROVA's control loop are a service, not a file you carry around. One repo authors them, one server hands them out, and consumer repos c… - [Registry](https://petrova.blog/concepts/registry/): registry.yaml is the single declarative list of repos governed by the petrova control plane. Every verb invocation looks up its target here first. A repo absent… - [Schema fingerprints](https://petrova.blog/concepts/schema-fingerprints/): A schema fingerprint is the first 12 hex chars of the SHA256 of a verb's schema file. Every emitted PR includes the fingerprint of the verb that produced it. Fi… - [Verbs](https://petrova.blog/concepts/verbs/): A verb is a typed, schema-validated action that emits a PR. PETROVA's entire write surface is the nine verbs catalogued at /verbs/ — there is no other path to c… ## Verb reference > The 9-verb action surface (typed JSON in, PR out). - [close_phase](https://petrova.blog/verbs/close_phase/): > Close an open phase. Requires a paired verificationround decision doc and explicit friction classification for every surfaced item. Marks the phase's decision… - [Common envelope](https://petrova.blog/verbs/common-envelope/): Shared types referenced by every verb schema. Single source of truth for cross-cutting types. - [declare_baseline](https://petrova.blog/verbs/declare_baseline/): > Ratify a new petrova baseline version (v2, v3, …) as a decision doc in petrova-codes. The verb's pre-flight runs the full server-side audit and refuses to pro… - [diagnose](https://petrova.blog/verbs/diagnose/): > Read-only collection of cross-cutting context across a target repo: current phase, open milestones, recent decisions, recent findings, failing CI checks. Retu… - [open_decision](https://petrova.blog/verbs/open_decision/): > Open a new dated decision doc in the target repo's docs/decisions/. Creates a PR adding a single file conforming to the repo's decision-doc template. The doc … - [petrova_install_playbook](https://petrova.blog/verbs/petrova_install_playbook/): > Deposit the petrova playbook (META-RULES.md, 00-bootstrap.md, mr-preamble.xml, progress-signal.xml, airlock-rules.xml, progress.schema.json) into a consumer r… - [petrova_onboard](https://petrova.blog/verbs/petrova_onboard/): > Initialise a registered repo's mechanical petrova floor: write .petrova/contract.yaml with default integration declarations + install .github/workflows/docs-i… - [PR body template](https://petrova.blog/verbs/pr-body-template/): Every write verb renders this template into the PR body. The YAML block is parsed by re-run detection — do not edit it manually on emitted PR… - [propose_fix](https://petrova.blog/verbs/propose_fix/): > Draft a fix PR grounded in a preceding diagnose run. Composes requestreview under the hood, but adds a hard binding to a diagnosisid and requires explicit MR-… - [request_merge_when_green](https://petrova.blog/verbs/request_merge_when_green/): > Open a PR (same surface as requestreview) AND mark it for auto-merge once branch protection / CI gates pass. Profile-restricted: only permitted on registry pr… - [request_review](https://petrova.blog/verbs/request_review/): > Generic write surface: open a PR with arbitrary file changes and request review. The lower-level primitive other write verbs may compose. Does NOT mark auto-m… - [start_phase](https://petrova.blog/verbs/start_phase/): > Open a new phase. Composes opendecision (writes phase-N-open.md) plus updatemilestone seeding for declared sub-milestones. Predecessor phase must be closed. - [update_milestone](https://petrova.blog/verbs/update_milestone/): > Add a new milestone or transition an existing one in the target repo's MILESTONES.md. State transitions are restricted: planned → active → complete | deferred… - [Verb catalogue](https://petrova.blog/verbs/): The nine action verbs the petrova control plane exposes. Each verb is schema-validated, idempotency-keyed, dry-run by default, and PR-emitting. - [verify_round](https://petrova.blog/verbs/verify_round/): > Record the output of a phase-close verification round. Creates a dated decision doc capturing surfaced items prior to classification (closephase consumes this… - [wire_integration](https://petrova.blog/verbs/wire_integration/): > Flip a registered consumer repo's .petrova/contract.yaml integration block from pending (or failing) to wired, with a validated evidence object. Generic over … ## CLI > Install, auth, command reference, configuration, output formats. - [Auth](https://petrova.blog/cli/auth/): --apply requires GitHub credentials. Read verbs (status, diagnose, validate, dashboard, verbs) work without auth — they read local clones. Dry-run write verbs a… - [CLI](https://petrova.blog/cli/): The PETROVA CLI is the primary surface for invoking verbs. Everything in this section walks you through installing it, configuring credentials, and using it day… - [Command reference](https://petrova.blog/cli/command-reference/): Every PETROVA CLI command, with synopsis, flags, and exit codes. - [Configuration](https://petrova.blog/cli/configuration/): Every PETROVA configuration knob is an environment variable. There is no config file — config-as-code wouldn't survive the registry shape, and config-as-flags w… - [Install](https://petrova.blog/cli/install/): The PETROVA CLI is a Node.js + TypeScript package living at petrova-codes/cli/. It builds to a self-contained dist/ and links as a global binary. - [Output formats](https://petrova.blog/cli/output-formats/): PETROVA CLI commands support up to three output formats. The default varies by command; the format is chosen via flags. ## Skills > Claude Code skill wrappers (see Skills section above for direct URLs). - [Install skills into a consumer repo](https://petrova.blog/skills/install/): Two skills that surface the petrova CLI to Claude Code sessions in any governed repo: - [petrova-act](https://petrova.blog/skills/petrova-act/): You are about to invoke a Petrova write verb. Every write verb produces a PR against the target repo, never a direct push. The PR body carries an idempotency ke… - [petrova-status](https://petrova.blog/skills/petrova-status/): Read-only inspection of one or more petrova-line repos. Three commands back this skill, all hitting local clones (no GitHub auth required): - [Refusal conditions](https://petrova.blog/skills/refusal-conditions/): These conditions cause petrova-act and petrova-status to refuse the action and surface the reason to the user. They are deliberate — refusal is correct behaviou… - [Skill helper scripts](https://petrova.blog/skills/scripts/): Utility scripts the skills shell out to. Source-of-truth for each is the file itself; the documented header (first 12 lines) appears here. ## Integrations > Contracts for external systems (KAHN agent fleets). - [diagnose then fix](https://petrova.blog/integrations/example-diagnose-then-fix/): A complete fleet run from triggering signal to merged PR. Numbers in brackets reference the steps in docs/integrations/kahn-fleet.md's end-to-end flow section. - [failure modes](https://petrova.blog/integrations/example-failure-modes/): Each scenario below shows the verb invocation, the structured failure output, and the fleet's recovery path. These are the cases CI fixtures should exercise onc… - [Integration contracts](https://petrova.blog/integrations/): How outside systems (agent fleets, CI pipelines, audit harnesses) interact with the petrova control plane. Each file in this directory is a contract: the rules,… - [KAHN agent fleets ↔ PETROVA](https://petrova.blog/integrations/kahn-fleet/): How KAHN-style fleets call petrova verbs to act on consumer repos without violating MR-6 (subagent additions go in AGENTS.xml), MR-7 (decisions are append-only,… ## Meta-rules > MR-1 through MR-12 — the cross-cutting invariants. - [Changing a meta-rule](https://petrova.blog/meta-rules/changing-an-mr/): Meta-rule changes are the highest-stakes documentation event in the petrova line. They ripple through every consumer repo's CLAUDE.md projection, every verb's u… - [Meta-rules (MR-1 ... MR-12)](https://petrova.blog/meta-rules/): > Cross-cutting invariants for the doc/agent system itself. These are > meta — they govern the docs that govern the code. If one of these is > violated, the sys… - [MR-1 — North-star outranks the backlog](https://petrova.blog/meta-rules/mr-1/) - [MR-10 — The verification round is mandatory at phase close](https://petrova.blog/meta-rules/mr-10/) - [MR-11 — Anti-shapes are named, catalogued, and watched](https://petrova.blog/meta-rules/mr-11/) - [MR-12 — The CLAUDE.md is the projection, not the source](https://petrova.blog/meta-rules/mr-12/) - [MR-13 — Intent and observation are separate state spaces](https://petrova.blog/meta-rules/mr-13/) - [MR-14 — Probes never auto-promote, only auto-demote](https://petrova.blog/meta-rules/mr-14/) - [MR-15 — The schema is the source of bootstrap questions](https://petrova.blog/meta-rules/mr-15/) - [MR-16 — The catalogue is realistic](https://petrova.blog/meta-rules/mr-16/): Every prompt in the EVA catalogue (eva-hq/prompts/) marked kind: verb-wrapper must name a verb: that exists in petrova-codes/spec/verbs/.schema.json. Verbs with… - [MR-17 — The playbook is physically present](https://petrova.blog/meta-rules/mr-17/): A consumer repo at role: production or experimental must carry .petrova/playbook/META-RULES.md (and the rest of the playbook deposit) under its default branch. … - [MR-2 — Friction surfaced in phase N's verification round becomes phase N+1's input](https://petrova.blog/meta-rules/mr-2/) - [MR-3 — Sibling files stay sibling](https://petrova.blog/meta-rules/mr-3/) - [MR-4 — Dates are absolute](https://petrova.blog/meta-rules/mr-4/) - [MR-5 — Direct push for small fixes; PR for checkpoints](https://petrova.blog/meta-rules/mr-5/) - [MR-6 — Subagents read from `AGENTS.xml`, not from inferred patterns](https://petrova.blog/meta-rules/mr-6/) - [MR-7 — Decision docs are append-only](https://petrova.blog/meta-rules/mr-7/) - [MR-8 — Invariants are numbered and stable](https://petrova.blog/meta-rules/mr-8/) - [MR-9 — Don't invent invariants](https://petrova.blog/meta-rules/mr-9/) ## Operator runbooks > Onboarding, auth, submodule bumps, failure recovery, fleet audits. - [ares wire rollout](https://petrova.blog/runbooks/ares-wire-rollout/): > Spec: docs/superpowers/specs/2026-05-01-petrova-ares-wire-spec.md > Plan: docs/superpowers/plans/2026-05-01-petrova-ares-wire-plan.md > Decision: docs/decisio… - [audit fleet activity](https://petrova.blog/runbooks/audit-fleet-activity/): When you need to know what a fleet has been doing — for a quarterly review, an incident response, or before broadening its fleetsallowed scope — this runbook wa… - [auth setup](https://petrova.blog/runbooks/auth-setup/): Step-by-step provisioning of credentials for petrova --apply. The user-facing summary is at /cli/auth/ — this page is the operator runbook with troubleshooting.… - [crumb wire rollout](https://petrova.blog/runbooks/crumb-wire-rollout/): > Spec: docs/superpowers/specs/2026-05-01-petrova-crumb-spec.md > Plan: docs/superpowers/plans/2026-05-01-petrova-crumb-plan.md > Decision: docs/decisions/2026-… - [integration spine rollout](https://petrova.blog/runbooks/integration-spine-rollout/): > Spec: docs/superpowers/specs/2026-04-30-petrova-integration-spine-design.md > Plan: docs/superpowers/plans/2026-04-30-petrova-integration-spine-plan.md - [lore cairnet wire rollout](https://petrova.blog/runbooks/lore-cairnet-wire-rollout/): Operator-facing playbook for ratifying lorecairnet: required across the 5 governed slugs that need it. Each wave produces one consumer-repo PR (decision doc + c… - [onboard repo](https://petrova.blog/runbooks/onboard-repo/): The end-to-end flow for admitting a new repo to the petrova control plane. After a successful run, the repo is reachable via every verb, visible in petrova stat… - [petrova host airlock setup](https://petrova.blog/runbooks/petrova-host-airlock-setup/): Audience: operator Frequency: one-time per environment RTO: ~15 minutes Related decision: docs/decisions/2026-05-10-per-user-auth-via-airlock-handoff.md - [rocky eva wire rollout](https://petrova.blog/runbooks/rocky-eva-wire-rollout/): Operator-facing playbook for the realignment ratified in docs/decisions/2026-05-06-rocky-ownership-and-eva-introduction.md. This runbook supersedes docs/runbook… - [submodule bump](https://petrova.blog/runbooks/submodule-bump/): PETROVA-HQ has two submodules: - [traceo wire rollout](https://petrova.blog/runbooks/traceo-wire-rollout/): > Spec: docs/superpowers/specs/2026-05-01-petrova-traceo-ariel-spec.md > Plan: docs/superpowers/plans/2026-05-01-petrova-traceo-ariel-plan.md > Decision: docs/d… - [verb failure recovery](https://petrova.blog/runbooks/verb-failure-recovery/): You ran a verb and got failed (or --apply errored before emission). This runbook is the operator-shaped recovery playbook, mapped to the errors[].code returned … ## Templates > Bootstrap-time templates copied into consumer repos. - [AGENTS.xml template](https://petrova.blog/templates/agents-xml/): The template the bootstrap agent (core/playbook/prompts/00-bootstrap.md) copies into a consumer repo. <> tokens are replaced from Phase-1 spec read… - [CLAUDE.md template](https://petrova.blog/templates/claude-md/): The template the bootstrap agent (core/playbook/prompts/00-bootstrap.md) copies into a consumer repo. <> tokens are replaced from Phase-1 spec read… - [docs/ scaffold](https://petrova.blog/templates/docs-scaffold/): Every petrova-line consumer repo inherits a standard docs/ shape on bootstrap. This page describes each directory's purpose and the rank graph that connects the… - [MILESTONES.md template](https://petrova.blog/templates/milestones-md/): The template the bootstrap agent (core/playbook/prompts/00-bootstrap.md) copies into a consumer repo. <> tokens are replaced from Phase-1 spec read… - [shared/ namespace](https://petrova.blog/templates/shared-namespace/): --- rank: shared outranks: [] --- - [shared/agent-fleet-methodology](https://petrova.blog/templates/shared-agent-fleet-methodology/): AGENTS.xml is the schema — who exists, what they read and write, how they hand off. This file is the grammar — the narrative rules that govern how the schema is… - [shared/conventions](https://petrova.blog/templates/shared-conventions/): Conventions that apply to every petrova-line repo. Project-specific conventions live in each repo's CLAUDE.md § "Conventions specific to this repo". - [shared/documentation-hierarchy](https://petrova.blog/templates/shared-documentation-hierarchy/): Every petrova-line repo organises docs/ by rank. The rank graph is a DAG declared in front-matter (MR-1); the drift-watcher subagent reads it when adjudicating … - [shared/meta-rules](https://petrova.blog/templates/shared-meta-rules/): The twelve MR-N cross-cutting invariants live at the canonical path core/templates/META-RULES.md and are copied verbatim into each consumer repo at bootstrap (t… - [shared/navigation-index](https://petrova.blog/templates/shared-navigation-index/): Standard navigation cheatsheet. Identical across petrova-line repos. - [shared/north-star-methodology](https://petrova.blog/templates/shared-north-star-methodology/): How to write and maintain a north-star doc. The how, never the what — project intent never lives in shared/. Each consumer repo owns its own docs/north-star/int… - [shared/phase-discipline](https://petrova.blog/templates/shared-phase-discipline/): Phases are the unit of progress. Acceptance-gated; closed only when their gates pass. This file codifies the rules that the phase prompts (01-phase-open, 02-pha… - [Templates overview](https://petrova.blog/templates/): Templates the bootstrap agent copies into a consumer repo on day 1. Top-level files become the consumer's control-loop documents; shared/ becomes the consumer's… ## Prompts > Paste-into-Claude-Code prompts that drive the control loop. - [ARES wire-up — turn a consumer repo's CI into ARES dashboard rows](https://petrova.blog/prompts/06-ares-wire/): > What this is. A single prompt that walks Claude Code through wiring one repo's CI/CD observability signal to ARES (cicd.devarno.cloud). Paste verbatim into a … - [Bootstrap prompt — paste into Claude Code on day 1](https://petrova.blog/prompts/00-bootstrap/): > What this is. A single prompt that turns a bare-bones scaffolded repo > (with detailed spec docs in docs/) into an agent-powered repo by > generating CLAUDE.m… - [CRUMB wire-up — turn a consumer repo's guidance docs into validated CRUMB flashcards](https://petrova.blog/prompts/08-crumb-wire/): > What this is. A single prompt that walks Claude Code through wiring one repo's guidance docs to CRUMB: author N flashcards as markdown under devarno-cloud/cru… - [Drift-check prompt](https://petrova.blog/prompts/04-drift-check/): > Paste when something feels off — a PR that doesn't quite serve the > intent, a doc that contradicts another, a phase scope that pulled > toward a named anti-s… - [EVA wire-up — register a consumer repo against the three EVA surfaces](https://petrova.blog/prompts/10-eva-wire/):