Skip to content
PETROVA

start_phase

Open a new phase. Composes open_decision (writes phase-N-open.md) plus update_milestone seeding for declared sub-milestones. Predecessor phase must be closed.

Upholds: MR-2 · MR-7 · MR-10 Side effects: Creates docs/decisions/-phase--open.md, modifies MILESTONES.md to add phase header + seeded milestones, opens a single PR carrying both.

Constraints

Section titled “Constraints”
  • REPO_IN_REGISTRY — target_repo must appear in registry.yaml.
  • PREDECESSOR_CLOSED — If phase_number > 1, predecessor phase decision doc must exist with status=closed.
  • PHASE_NOT_OPEN — phase_number must not already have an open phase decision doc.
  • ACCEPTANCE_GATE_NONEMPTY — acceptance_gate must contain ≥1 measurable criterion.
  • FRICTION_INPUT_DECLARED — If predecessor phase’s verification round produced deferred items, friction_carryover must list them or explicitly declare ‘none-deferred’.

Input shape

Section titled “Input shape”
  • phase_number integer (required)
  • name string (required)
  • scope string (required)
  • acceptance_gate array (required)
    • items:
      • claim string (required)
      • evidence_kind string (required) enum: script, metric, fixture, test, human-signoff
      • evidence_ref string
  • seeded_milestones array
    • items:
      • id → MilestoneId (required)
      • title string (required)
      • acceptance_criteria array
  • friction_carryover array — List of deferred milestone IDs from predecessor phase, or single literal ‘none-deferred’.

Output shape

Section titled “Output shape”
  • phase_id string
  • decision_doc_path string
  • milestones_seeded array
  • pr → PRRef
  • diff_preview → DiffPreview

Example

Section titled “Example”

Input:

{
  "envelope": {
    "verb": "start_phase",
    "target_repo": "kahn-hq",
    "idempotency_key": "c5d2bb5d3a0f98246d7c0e9f3a4b5c6d7e8f9012b3c4d5e6f7a8b9c0d1e2f304",
    "dry_run": true,
    "actor": "human:alex@devarno.com",
    "triggered_by": {
      "kind": "phase_close",
      "ref": "docs/decisions/2026-04-29-phase-7-close.md"
    }
  },
  "params": {
    "phase_number": 8,
    "name": "Post-Phase-7 re-probe + carryover",
    "scope": "Operator-driven SPA re-probe; absorb M7.8.2 friction.",
    "acceptance_gate": [
      {
        "claim": "Visitor-grade probe completed against kahn.host",
        "evidence_kind": "human-signoff"
      },
      {
        "claim": "Friction round classifies all surfaced items",
        "evidence_kind": "fixture",
        "evidence_ref": "docs/verification/phase-8-friction.md"
      }
    ],
    "seeded_milestones": [
      {
        "id": "M8.1.1",
        "title": "Operator re-probe",
        "acceptance_criteria": [
          "Probe transcript captured"
        ]
      }
    ],
    "friction_carryover": [
      "M7.8.2"
    ]
  }
}

Output (output_dry_run):

{
  "envelope": {
    "verb": "start_phase",
    "status": "dry_run",
    "idempotency_key": "c5d2bb5d3a0f98246d7c0e9f3a4b5c6d7e8f9012b3c4d5e6f7a8b9c0d1e2f304",
    "mr_citations": [
      "MR-2",
      "MR-7",
      "MR-10"
    ]
  },
  "result": {
    "phase_id": "Phase-8",
    "decision_doc_path": "docs/decisions/2026-04-29-phase-8-open.md",
    "milestones_seeded": [
      "M8.1.1"
    ],
    "diff_preview": {
      "files": [
        {
          "path": "docs/decisions/2026-04-29-phase-8-open.md",
          "operation": "create"
        },
        {
          "path": "MILESTONES.md",
          "operation": "modify"
        }
      ],
      "branch": "petrova/start-phase/phase-8",
      "commit_message": "phase: open Phase 8 (idempotency: c5d2bb5d3a0f9824)"
    }
  }
}

Recipe

Section titled “Recipe”

Schema: spec/verbs/start_phase.schema.json Upholds: MR-2, MR-7, MR-10. Emits: PR creating docs/decisions/<today>-phase-<N>-open.md and optionally appending seeded milestones to MILESTONES.md.

When to use

Section titled “When to use”

Opening Phase N. The previous phase must be closed (or this is Phase 1).

Required params

Section titled “Required params”
{
  "phase_number": <int>,
  "name": "<short phase name>",
  "scope": "<one paragraph: what this phase covers>",
  "acceptance_gate": [
    {"claim": "<measurable claim>", "evidence_kind": "script|metric|fixture|test|human-signoff"}
  ]
}

Optional:

  • seeded_milestones: [{ id, title, acceptance_criteria? }]
  • friction_carryover: array of milestone IDs from prior phase, OR the string literal "none-deferred" if nothing carried.

Constraints

Section titled “Constraints”
  • Predecessor phase must be closed (verified from phase-<N-1>-close.md decision doc).
  • acceptance_gate length ≥ 1.
  • phase_number not already opened.
  • If predecessor had deferred friction, friction_carryover must list it or explicitly declare none-deferred.

Dry-run

Section titled “Dry-run”
Terminal window
cat > /tmp/petrova-input.json <<'JSON'
{
  "phase_number": 8,
  "name": "Post-Phase-7 re-probe + carryover",
  "scope": "Operator-driven SPA re-probe; absorb M7.8.2 friction.",
  "acceptance_gate": [
    {"claim": "Visitor-grade probe completed against kahn.host", "evidence_kind": "human-signoff"},
    {"claim": "Friction round classifies all surfaced items", "evidence_kind": "fixture", "evidence_ref": "docs/verification/phase-8-friction.md"}
  ],
  "seeded_milestones": [
    {"id": "M8.1.1", "title": "Operator re-probe", "acceptance_criteria": ["Probe transcript captured"]}
  ],
  "friction_carryover": ["M7.8.2"]
}
JSON
petrova start_phase kahn-hq --input /tmp/petrova-input.json
Section titled “Related”