2026-05-13-petrova-onboarding-flow-v2

---

title: PETROVA onboarding flow (v2) — canonical 5-step path for new fleet repos date: 2026-05-13 status: ratified mr_compliance: [MR-7, MR-13, MR-14]

Context

Before Baseline v2, “onboarding a repo to petrova” was a prose-only flow defined in core/prompts/00-bootstrap.md (canonical in eva-hq). Operators wrote CLAUDE.md / MILESTONES.md / AGENTS.xml / north-star by hand, hand-edited registry.yaml, and the only mechanical artefact was the docs-invariants.yml workflow installed manually (later batch-propagated in Baseline v1 Phase 4).

Baseline v2 (2026-05-13) shipped two verbs that codify the mechanical floor of onboarding:

• petrova_onboard writes .petrova/contract.yaml and installs docs-invariants.yml in a consumer repo.
• declare_baseline ratifies a new fleet baseline version with an audit-pre-flight gate.

Plus two new audit checks (MR-14 onboarding-complete, MR-15 workflow-drift) provide the feedback signal on whether a repo’s mechanical floor is complete.

Several artefacts now overlap or compose: the prose bootstrap, the verb, the registry edit, the audit checks. The next operator who needs to onboard a repo has no single canonical document describing the right order. This ADR is that document.

Decision

The canonical onboarding flow for any new fleet repo is five sequential steps. Steps 1–2 are operator-led prose; steps 3–5 are verb-driven mechanical. Steps cannot be reordered: each produces an artefact the next step consumes or audits.

Step 1 — Prose bootstrap

Operator opens core/prompts/00-bootstrap.md (canonical in eva-hq) and walks the Q1–Q8 sequence with the LLM, producing in the target repo:

• docs/north-star/intent.md (+ realignment-criteria, docs/north-star/README.md nav)
• MILESTONES.md
• AGENTS.xml (declaring subagent roles, MR-6)
• CLAUDE.md (MUST reference docs/north-star/ or MILESTONES.md to satisfy MR-12)
• docs/decisions/YYYY-MM-DD-bootstrap-answers.md — the operator’s Q1–Q8 answers as a decision doc. This is the artefact step 3 consumes.

The EVA prompt petrova-bootstrap (kind: verb-wrapper after Baseline v3 S1.3, but really wraps the prose flow not a verb) is the catalogue entry for this step. No automation; this step is content judgement.

Step 2 — Registry entry in petrova-codes

Operator opens a PR against petrova-codes/registry.yaml adding the new slug. Required fields:

• slug, url, default_branch, role, profile, added
• fleets_allowed: [] by default — agent automation only enabled by a subsequent governance change with explicit notes:
• integrations_applicability declaring required/optional/not_applicable per integration (ares, traceo, crumb, rocky, eva)

PR-only edit; no verb wraps this today. Step 3’s verb will refuse with REPO_IN_REGISTRY until this lands.

Step 3 — petrova_onboard verb

From petrova-codes, run the v2 verb:

PETROVA_ALLOW_HUMAN_OVERRIDE=1 \
PETROVA_APP_INSTALLATION_ID=<owner-installation-id> \
node cli/dist/index.js petrova_onboard <slug> \
  --input bootstrap-input.json \
  --actor "human:<email>" \
  --triggered-by-kind human_request \
  --triggered-by-ref "petrova-onboarding" \
  --apply

Where bootstrap-input.json is:

{
  "bootstrap_answers_path": "docs/decisions/YYYY-MM-DD-bootstrap-answers.md",
  "install_workflow": true
}

The verb’s pre-flight reads the cited bootstrap-answers path (BOOTSTRAP_ANSWERS_EXIST), refuses if .petrova/contract.yaml already exists (CONTRACT_DOES_NOT_EXIST), and emits a PR in the consumer repo on branch petrova/onboard/<slug> carrying .petrova/contract.yaml (all integrations pending unless overridden) and .github/workflows/docs-invariants.yml.

Operator reviews + merges the PR.

The EVA prompt petrova-onboard (rewritten in Baseline v3 S1.1 to match the verb) is the catalogue entry.

Step 4 — First sweep

From petrova-codes:

node cli/dist/index.js sweep-state --slug <slug>

Populates state/<slug>.yaml.actual_contract_sha (proves the sweep observed the contract). This is the signal MR-14 (auditMr14) gates on — the row flips from fail to pass after this sweep. Commit the state delta to petrova-codes’ main.

Step 5 — Phase-1 entry (when ready)

From petrova-codes, run the start_phase verb to open Phase-1:

node cli/dist/index.js start_phase <slug> --input phase-1-input.json --apply

After merge, the slug renders as onboarded (filled cells) on /console/phases. Until then, it renders as no_phases_yet (outline circles) — explicitly the “registered + mechanical floor in place, but pre-Phase-1” state introduced by the Baseline v1 phases tri-state.

Acceptance gates per step

Step	Gate	Failure mode
1	Operator produces 5 artefacts in target repo	Step 3 verb refuses (BOOTSTRAP_ANSWERS_EXIST)
2	Slug appears in registry.yaml	Step 3 verb refuses (REPO_IN_REGISTRY)
3	PR merged in consumer repo with both files	MR-14 stays fail
4	state/<slug>.yaml.actual_contract_sha non-null	MR-14 stays fail
5	Phase-1 ADR + start_phase verb result merged	Dashboard shows no_phases_yet indefinitely

Alternatives considered

• Single mega-verb for the whole flow (rejected). Combining content authoring (Step 1) with mechanical writes (Step 3) violates the “narrow compliance verb” scope chosen for petrova_onboard in Baseline v2. Content judgement should stay prose-driven.
• Retrofit existing dormants automatically (rejected per Baseline v2 § “operator confirmation”). The verb is forward-only; existing dormants stay role: scaffold with null .petrova/contract.yaml until their operator chooses to bootstrap.
• Skip Step 2 (registry-first) and have Step 3 verb create the registry entry (rejected). Cross-repo write paths from one verb introduce auth + review-gate complexity that the current verb pattern explicitly avoids. Registry edits stay PR-only.

Consequences

For operators: the next new repo joining the fleet follows this flow. The EVA catalogue prompts (petrova-bootstrap, petrova-onboard, petrova-decision-doc, petrova-phase-open) are paste-ready for each step. The super-prompt gist (v01t-io/meta-prompts/artefacts/devarno/eva-super-prompts.md) will expose /eva.onboard <slug> in Wave 2 of Baseline v3 to compose Steps 1+3 into a single operator-facing flow with pause-point at Step 2 (PR review).

For audit: MR-14 + MR-15 surface incomplete onboardings on /console/governance. A repo registered without a contract (Steps 1–2 done, Step 3 skipped) shows MR-14 fail. A repo with a contract but missing the workflow shows MR-15 fail. A repo registered + contract + workflow but no first sweep shows MR-14 fail until Step 4 runs.

For the dashboard: /console/phases renders tri-state — not_onboarded (Step 2 skipped), no_phases_yet (Steps 1–4 done, Step 5 pending), onboarded (all five steps done). The new RepoLink category icons (Baseline v2 follow-up) classify the repo by its product domain.

References

• Baseline v1 ADR: docs/decisions/2026-05-13-petrova-baseline-v1.md
• Baseline v2 ADR: docs/decisions/2026-05-13-petrova-baseline-v2.md
• v3 catalogue-realignment plan: ~/.claude/plans/glittery-popping-bear.md (operator-local)
• Verb specs: spec/verbs/petrova_onboard.schema.json, spec/verbs/declare_baseline.schema.json
• EVA prompt catalogue: eva.re/catalog/
• Super-prompts gist: v01t-io/meta-prompts/artefacts/devarno/eva-super-prompts.md