Skip to content
PETROVA

Verbs

A verb is a typed, schema-validated action that emits a PR. PETROVA’s entire write surface is the 16 petrova.act.* write verbs catalogued at /verbs/ — there is no other path to changing a governed repo via the control plane. (spec/verbs/ holds 18 verb schemas in total: those 16, plus the read-only diagnose and the CLI-only daedalus_distribute.) For how verbs sit among the other governance gates, see the governance model.

The mechanical pipeline

Section titled “The mechanical pipeline”

Every verb invocation follows the same shape:

%%{init: {'flowchart': {'htmlLabels': false, 'curve': 'linear', 'nodeSpacing': 50, 'rankSpacing': 60, 'padding': 14}}}%%
flowchart TD
    I([typed input])
    S["schema
validation"]
    K["constraint
checks"]
    D[/"diff preview
no side effects"/]
    A["branch +
Contents-API commits"]
    PR["PR open"]
    O([output
envelope])

    I --> S --> K
    K -- "--dry-run" --> D
    K -- "--apply" --> A --> PR
    D --> O
    PR --> O

    classDef peer fill:transparent,stroke-width:1px;
    classDef gate fill:#c8631f,stroke:#7a3a10,color:#fffaf2,font-weight:600;
    class I,D,A,PR,O peer;
    class S,K gate;

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

Section titled “Composition”

Some verbs compose others under the hood:

CompositeComposesWhen
propose_fixrequest_review (default) or request_merge_when_greenAfter a diagnose run, when proposing a code fix.
start_phaseopen_decision + update_milestoneOpening Phase N with seeded milestones in one PR.
close_phaseopen_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

Section titled “Why verbs, not arbitrary edits”

The narrowness is the point. A fixed catalogue of write verbs covers 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, onboarding a repo, wiring an integration, editing the registry. 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

Section titled “See also”