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 changing a governed repo via the control plane.

The mechanical pipeline

Every verb invocation follows the same shape:

typed input ─► schema validation ─► constraint checks ─►
   ├── dry_run path  ─► diff preview, no side effects
   └── apply path    ─► branch + Contents-API commits ─► PR open ─► output envelope

Each stage:

1. Typed input. The caller (CLI, skill, fleet) builds JSON conforming to the verb’s input schema.
2. Schema validation. Inputs validate against spec/verbs/<verb>.schema.json before any side-effect — even in --apply mode. Validation failure aborts.
3. Constraint checks. Each verb declares enumerable constraints (e.g. DEFERRED_HAS_TARGET, NO_PRIVILEGED_PATHS). Unmet constraints surface as structured errors, not silent failures.
4. Dry-run vs apply. Default is dry-run — produces a diff_preview matching what the apply would emit. See dry-run vs apply.
5. PR emission. Apply mode opens a branch, commits files via the GitHub Contents API, and creates a PR with the verb’s metadata embedded in the body. See API-first.
6. Output envelope. Every verb returns the same envelope shape: verb, status (dry_run | applied | skipped_idempotent | failed), idempotency_key, mr_citations[], errors[].

Composition

Some verbs compose others under the hood:

Composite	Composes	When
propose_fix	request_review (default) or request_merge_when_green	After a diagnose run, when proposing a code fix.
start_phase	open_decision + update_milestone	Opening Phase N with seeded milestones in one PR.
close_phase	open_decision (the close-out doc)	After a verify_round has surfaced friction items.

Composition is explicit, not implicit. The verb declares what it composes in its schema; the rendered PR body cites both the wrapping verb and the composed verb’s MRs.

Why verbs, not arbitrary edits

The narrowness is the point. Nine verbs cover every petrova-shaped write — opening a decision, updating a milestone, opening or closing a phase, recording a verification round, requesting review, requesting auto-merge, proposing a fix grounded in a diagnose. A fleet that wants to do something outside this catalogue must surface the gap to a human, not improvise.

This is the same boundary that lets the control plane stay thin and the audit trail stay legible.

See also

• Verb catalogue — the 9-verb table with one-line descriptions.
• Common envelope — the shared input/output shape.
• Idempotency keys — re-run detection.