Skip to content
PETROVA

verify_round

Record the output of a phase-close verification round. Creates a dated decision doc capturing surfaced items prior to classification (close_phase consumes this doc and applies the classifications). Mandatory at every phase close per MR-10, even when no friction surfaces.

Upholds: MR-10 Side effects: Creates docs/decisions/-phase--friction-round.md, opens a PR. Does NOT classify items — that’s close_phase’s job.

Constraints

Section titled “Constraints”
  • REPO_IN_REGISTRY — target_repo must appear in registry.yaml.
  • PHASE_OPEN — Phase must be open. verify_round on a closed phase is forbidden.
  • ITEMS_NONEMPTY_OR_EXPLICIT_NONE — items must contain ≥1 entry, or include a single sentinel item with id=‘ROUND-CLEAN’ and description naming what was checked. Empty arrays are not permitted (silent rounds violate MR-10’s spirit).

Input shape

Section titled “Input shape”
  • phase_number integer (required)
  • items array (required)
    • items:
      • id string (required)
      • description string (required)
      • surfaced_by string — Which check / artefact / human surfaced this item.
      • evidence_ref string
  • checks_performed array (required) — What was inspected during the round (test runs, doc audits, dashboard reviews, etc.).
  • round_lead string — Who led the round — subagent or human.

Output shape

Section titled “Output shape”
  • phase_id string
  • round_doc_path string
  • item_count integer
  • pr → PRRef
  • diff_preview → DiffPreview

Example

Section titled “Example”

Input:

{
  "envelope": {
    "verb": "verify_round",
    "target_repo": "kahn-hq",
    "idempotency_key": "e7f4dd7f5c20bb468f9e2a1b5c6d7e8f9012b3c4d5e6f7a8b9c0d1e2f3041526",
    "dry_run": true,
    "actor": "fleet:kahn-reviewer",
    "triggered_by": {
      "kind": "phase_close",
      "ref": "Phase-7"
    }
  },
  "params": {
    "phase_number": 7,
    "items": [
      {
        "id": "F7-1",
        "description": "Live-dot fails for sub-second runs",
        "surfaced_by": "manual smoke",
        "evidence_ref": "docs/findings/20260428-1100-livedot-subsec.md"
      },
      {
        "id": "F7-2",
        "description": "M7.8.2 re-probe outstanding",
        "surfaced_by": "phase scope review"
      }
    ],
    "checks_performed": [
      "full e2e matrix",
      "visual baseline diff",
      "doc-invariants CI",
      "operator scan"
    ],
    "round_lead": "subagent:reviewer-final"
  }
}

Output (output_dry_run):

{
  "envelope": {
    "verb": "verify_round",
    "status": "dry_run",
    "idempotency_key": "e7f4dd7f5c20bb468f9e2a1b5c6d7e8f9012b3c4d5e6f7a8b9c0d1e2f3041526",
    "mr_citations": [
      "MR-10"
    ]
  },
  "result": {
    "phase_id": "Phase-7",
    "round_doc_path": "docs/decisions/2026-04-29-phase-7-friction-round.md",
    "item_count": 2,
    "diff_preview": {
      "files": [
        {
          "path": "docs/decisions/2026-04-29-phase-7-friction-round.md",
          "operation": "create"
        }
      ],
      "branch": "petrova/verify-round/phase-7",
      "commit_message": "verify-round: phase 7 (2 items, idempotency: e7f4dd7f5c20bb46)"
    }
  }
}

Recipe

Section titled “Recipe”

Schema: spec/verbs/verify_round.schema.json Upholds: MR-10 (verification round mandatory at phase close). Emits: PR creating docs/decisions/<today>-phase-<N>-friction-round.md.

When to use

Section titled “When to use”

Mandatory at every phase close. Run it BEFORE close_phase — the close references this round’s doc.

Even if no friction surfaced, run it with a single sentinel item (id: "ROUND-CLEAN") naming what was checked. Empty rounds violate MR-10’s spirit.

Required params

Section titled “Required params”
{
  "phase_number": <int>,
  "items": [
    {"id": "F<N>-<n>", "description": "<what surfaced>", "surfaced_by": "<source>", "evidence_ref": "<path>"}
  ],
  "checks_performed": ["<check 1>", "<check 2>"]
}

Item id pattern: F<phase>-<seq> (e.g. F7-1, F7-2) OR the literal ROUND-CLEAN for clean-round sentinel.

Optional: round_lead (subagent or human who led the round).

Constraints

Section titled “Constraints”
  • items array non-empty. Use ROUND-CLEAN sentinel if nothing surfaced — empty rounds are forbidden.
  • checks_performed non-empty.

Dry-run

Section titled “Dry-run”
Terminal window
cat > /tmp/petrova-input.json <<'JSON'
{
  "phase_number": 7,
  "items": [
    {"id": "F7-1", "description": "Live-dot fails for sub-second runs", "surfaced_by": "manual smoke", "evidence_ref": "docs/findings/20260428-1100-livedot-subsec.md"},
    {"id": "F7-2", "description": "M7.8.2 re-probe outstanding", "surfaced_by": "phase scope review"}
  ],
  "checks_performed": ["full e2e matrix", "visual baseline diff", "doc-invariants CI", "operator scan"],
  "round_lead": "subagent:reviewer-final"
}
JSON
petrova verify_round kahn-hq --input /tmp/petrova-input.json

What this verb does NOT do

Section titled “What this verb does NOT do”
  • Does not classify items. Classification happens in close_phase.
  • Does not auto-create followup milestones for deferred items. close_phase references the items; the human (or update_milestone) creates the follow-ons.
Section titled “Related”