petrova_onboard

Initialise a registered repo’s mechanical petrova floor: write .petrova/contract.yaml with default integration declarations + install .github/workflows/docs-invariants.yml if missing. Narrow compliance verb — does NOT generate CLAUDE.md / MILESTONES.md / AGENTS.xml / north-star (those stay prose-driven via 00-bootstrap.md). The verb’s job is to make the mechanical floor harder to skip.

Upholds: MR-13 · MR-14 Side effects: Creates a branch petrova/onboard/ in target_repo. Adds .petrova/contract.yaml and (if missing) .github/workflows/docs-invariants.yml. Opens a PR.

Constraints

REPO_IN_REGISTRY — target_repo must appear in registry.yaml.
BOOTSTRAP_ANSWERS_EXIST — bootstrap_answers_path must resolve to a markdown file in target_repo’s default_branch (verifies the Q1–Q8 answers from 00-bootstrap.md are already written down).
CONTRACT_DOES_NOT_EXIST — target path .petrova/contract.yaml must not already exist in target_repo’s default_branch (no double-bootstrap; rerun is a different verb).
FLEETS_ALLOWED_EMPTY — Standard policy gate; human override via PETROVA_ALLOW_HUMAN_OVERRIDE=1 + actor=human:.

Input shape

bootstrap_answers_path string (required) — Path within target_repo (e.g. docs/decisions/2026-05-13-bootstrap-answers.md) to the doc capturing Q1–Q8 answers from 00-bootstrap.md. Verb verifies path resolves; does not validate content.
integrations object — Optional override of the default integration declarations (all pending). Use when the repo already has evidence to declare for one or more integrations at onboarding time.
- ares → #/$defs/IntegrationDecl
- traceo → #/$defs/IntegrationDecl
- crumb → #/$defs/IntegrationDecl
- rocky → #/$defs/IntegrationDecl
- eva → #/$defs/IntegrationDecl
install_workflow boolean — Whether to install .github/workflows/docs-invariants.yml from the canonical petrova-codes template if absent. Default true. Set false only for repos that intentionally customise the workflow (rare).

Output shape

contract_path string
workflow_installed boolean
pr → PRRef
diff_preview → DiffPreview

Example

Input:

{
  "envelope": {
    "verb": "petrova_onboard",
    "target_repo": "oompa-tools",
    "idempotency_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "dry_run": true,
    "actor": "human:alex@devarno.com",
    "triggered_by": {
      "kind": "human_request",
      "ref": "petrova-codes:baseline-v2-s2"
    }
  },
  "params": {
    "bootstrap_answers_path": "docs/decisions/2026-05-07-extract-from-choco-hq.md",
    "install_workflow": true
  }
}

Output (output_dry_run):

{
  "envelope": {
    "verb": "petrova_onboard",
    "status": "dry_run",
    "idempotency_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "mr_citations": [
      "MR-13",
      "MR-14"
    ]
  },
  "result": {
    "contract_path": ".petrova/contract.yaml",
    "workflow_installed": true,
    "diff_preview": {
      "files": [
        {
          "path": ".petrova/contract.yaml",
          "operation": "create",
          "size_bytes": 612
        },
        {
          "path": ".github/workflows/docs-invariants.yml",
          "operation": "create",
          "size_bytes": 8743
        }
      ],
      "branch": "petrova/onboard/oompa-tools",
      "commit_message": "feat(petrova): onboard oompa-tools (idempotency: 0123456789ab)"
    }
  }
}

Recipe