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 key so re-runs detect existing PRs and become no-ops.

Workflow

Follow these steps in order. Do not skip steps.

1. Identify the target repo

bash "${PETROVA_HOME:-$HOME/code/workspace/petrova-hq}/skills/petrova-act/scripts/repo-slug.sh"

This prints the slug derived from git remote get-url origin (matching against registry.yaml). If it errors with REPO_NOT_IN_REGISTRY, refuse the action and tell the human:

This repo isn’t in the petrova registry. To onboard, open a PR against ${PETROVA_HOME}/registry.yaml adding an entry for this repo.

If it errors with NO_GIT_REMOTE, ask the human to specify --repo <slug> explicitly.

2. Pick the verb

The eight write verbs and their short hooks:

Verb	Use when
open_decision	Recording a non-trivial decision (architectural call, scope change, supersession).
update_milestone	Adding a new milestone, marking active/complete/deferred/retired.
start_phase	Opening Phase N (creates phase-N-open decision doc + seeds milestones).
close_phase	Closing Phase N after a verification round (requires sign_off.human).
verify_round	Recording the mandatory phase-close verification round (MR-10).
request_review	Generic file changes — open a PR for human review.
request_merge_when_green	Same, but enable auto-merge. Only on permissive-profile repos.
propose_fix	Fix grounded in a recent diagnose run (within 24h). Composes request_review or request_merge_when_green.

Each verb’s exact contract is in ${PETROVA_HOME}/spec/verbs/<verb>.schema.json. Each verb has a recipe file at skills/petrova-act/verbs/<verb>.md — read the relevant one before composing params.

3. Compose params and dry-run

Write the params JSON to a temp file:

cat > /tmp/petrova-input.json <<'JSON'
{
  ... verb-specific params, NOT including envelope fields ...
}
JSON

Run dry-run:

petrova <verb> <slug> --input /tmp/petrova-input.json

(If petrova is not on PATH: node "${PETROVA_HOME}/cli/dist/index.js" <verb> <slug> --input /tmp/petrova-input.json.)

Expected output: <verb> → dry_run <key> plus a diff preview. Failures appear as <verb> → failed with structured error codes (FIELD_PATTERN, NO_PRIVILEGED_PATHS, DEFERRED_HAS_TARGET, etc.).

Show the dry-run output to the human verbatim. Do not summarize away the diff preview — the human’s go-ahead is on the actual files that will land.

4. Apply (only after explicit human go-ahead)

If the human says go ahead AND PETROVA_GITHUB_TOKEN (or GitHub App env vars) is set:

petrova <verb> <slug> --input /tmp/petrova-input.json --apply

Expected: <verb> → applied <key> with PR URL. Or <verb> → skipped_idempotent if a prior run already opened a PR with the same key.

Show the PR URL to the human and stop. Do not assume the PR will merge — branch protection + CI + reviewer approval remain the human gate.

Refusal conditions

• Repo slug not in registry.yaml → refuse, suggest onboarding PR.
• --apply requested without auth env vars → refuse, point at cli/README.md for setup.
• File paths matching ^\.github/workflows/, *.env, ^secrets/, or ^deploy/credentials/ → refuse unconditionally. Privileged paths require human edit.
• Verb expects actor starting with fleet:, but registry’s fleets_allowed doesn’t include the fleet → refuse, name the registry entry that needs updating.
• propose_fix invoked without a fresh diagnose run for the same repo → run petrova diagnose <slug> first, then retry.

Output discipline

When reporting the result to the human:

• For dry-run: state the verb, slug, key (first 12 chars), MR citations, and the diff preview’s file list.
• For applied: state the verb, slug, key, PR URL. Nothing else.
• For failed: state the verb, slug, every error’s code + message. Do not silently retry — investigate the cause first.

What you do not do

• Do not push directly to a target branch. Always emit PR.
• Do not invent verb names. The eight above are the surface; if a need doesn’t fit, surface that gap to the human (probably a TASKSET 8 question).
• Do not edit the petrova metadata YAML block in any PR body. That block is parsed by re-run detection.
• Do not bypass dry-run. Always show the diff to the human first unless they have already given a standing instruction for this exact verb on this exact repo.