close_phase

Close an open phase. Requires a paired verification_round decision doc and explicit friction classification for every surfaced item. Marks the phase’s decision doc status=closed via supersession-style edit (only permitted edit to a closed-side doc per MR-7 is adding the back-reference).

Upholds: MR-2 · MR-7 · MR-10 Side effects: Creates docs/decisions/-phase--close.md, opens a PR. Does NOT auto-mark milestones complete — that requires separate update_milestone calls per milestone with evidence.

Constraints

REPO_IN_REGISTRY — target_repo must appear in registry.yaml.
PHASE_OPEN — Phase must currently be open (paired phase--open doc exists with status=open).
VERIFICATION_ROUND_PRESENT — verification_round_doc_path must reference an existing decision doc with slug pattern phase--friction-round or similar, dated within 7 days.
ALL_FRICTION_CLASSIFIED — Every item in the verification round’s findings must appear in friction_classifications with classification ∈ {closed, in-budget, deferred}.
DEFERRED_HAS_TARGET — Each item with classification=deferred must specify deferred_to_milestone in a later phase (MR-2).
ACCEPTANCE_GATE_PASSED — phase--open’s acceptance_gate claims must all be checked off with evidence.
HUMAN_COUNTERSIGN_PRESENT — sign_off.human must be non-empty. Phase close without human countersign remains open (MR-10).

Input shape

phase_number integer (required)
verification_round_doc_path string (required)
friction_classifications array (required)
- items:
  - item_id string (required)
  - description string
  - classification string (required) enum: closed, in-budget, deferred
  - deferred_to_milestone → MilestoneId
  - rationale string
evidence array (required)
- items:
  - claim string (required)
  - evidence_path string (required)
sign_off object (required)
- subagent string
- human string (required)
summary string — Free-text close-out summary.

Output shape

phase_id string
close_doc_path string
deferred_milestones array
pr → PRRef
diff_preview → DiffPreview

Example

Input:

{
  "envelope": {
    "verb": "close_phase",
    "target_repo": "kahn-hq",
    "idempotency_key": "d6e3cc6e4b1faa357e8d1f0a4b5c6d7e8f9012b3c4d5e6f7a8b9c0d1e2f30415",
    "dry_run": true,
    "actor": "human:alex@devarno.com",
    "triggered_by": {
      "kind": "phase_close",
      "ref": "Phase-7"
    }
  },
  "params": {
    "phase_number": 7,
    "verification_round_doc_path": "docs/decisions/2026-04-28-phase-7-friction-round.md",
    "friction_classifications": [
      {
        "item_id": "F7-1",
        "classification": "closed",
        "rationale": "single-line bug fixed in same round"
      },
      {
        "item_id": "F7-2",
        "classification": "deferred",
        "deferred_to_milestone": "M8.1.1",
        "rationale": "operator-grade re-probe"
      }
    ],
    "evidence": [
      {
        "claim": "Bundle budget enforced in CI",
        "evidence_path": "docs/verification/phase-7-bundle.md"
      }
    ],
    "sign_off": {
      "subagent": "reviewer-final",
      "human": "alex@devarno.com 2026-04-29"
    },
    "summary": "Phase 7 implementation closes with one deferred milestone (M8.1.1) per MR-2."
  }
}

Output (output_dry_run):

{
  "envelope": {
    "verb": "close_phase",
    "status": "dry_run",
    "idempotency_key": "d6e3cc6e4b1faa357e8d1f0a4b5c6d7e8f9012b3c4d5e6f7a8b9c0d1e2f30415",
    "mr_citations": [
      "MR-2",
      "MR-7",
      "MR-10"
    ]
  },
  "result": {
    "phase_id": "Phase-7",
    "close_doc_path": "docs/decisions/2026-04-29-phase-7-close.md",
    "deferred_milestones": [
      "M8.1.1"
    ],
    "diff_preview": {
      "files": [
        {
          "path": "docs/decisions/2026-04-29-phase-7-close.md",
          "operation": "create"
        }
      ],
      "branch": "petrova/close-phase/phase-7",
      "commit_message": "phase: close Phase 7 (idempotency: d6e3cc6e4b1faa35)"
    }
  }
}

Recipe

Schema: spec/verbs/close_phase.schema.json Upholds: MR-2, MR-7, MR-10. Emits: PR creating docs/decisions/<today>-phase-<N>-close.md.

Prerequisite

verify_round for this phase MUST already be applied — close_phase references the resulting friction-round doc. If you haven’t run verify_round yet, run it first.

When to use

Closing Phase N after the verification round has surfaced and classified friction.

Required params

{
  "phase_number": <int>,
  "verification_round_doc_path": "docs/decisions/<date>-phase-<N>-friction-round.md",
  "friction_classifications": [
    {"item_id": "F<N>-1", "classification": "closed | in-budget | deferred", "deferred_to_milestone": "<MX.Y.Z>?", "rationale": "<reason>"}
  ],
  "evidence": [
    {"claim": "<acceptance_gate claim>", "evidence_path": "docs/verification/<file>.md"}
  ],
  "sign_off": {"human": "<name + ISO date>"}
}

Optional: summary (close-out note in the decision doc), sign_off.subagent.

Critical constraints (cause of most failures)

friction_classifications must cover EVERY item from the verification round. Missing items → ALL_FRICTION_CLASSIFIED failure (live check; dry-run accepts whatever you provide).
Each deferred item MUST have deferred_to_milestone in a later phase (MR-2). Verb fails with DEFERRED_HAS_TARGET otherwise.
sign_off.human must be non-empty. A close without human countersign is open per MR-10. Verb fails with HUMAN_COUNTERSIGN_PRESENT.

Dry-run

cat > /tmp/petrova-input.json <<'JSON'
{
  "phase_number": 7,
  "verification_round_doc_path": "docs/decisions/2026-04-28-phase-7-friction-round.md",
  "friction_classifications": [
    {"item_id": "F7-1", "classification": "closed", "rationale": "single-line bug fixed in same round"},
    {"item_id": "F7-2", "classification": "deferred", "deferred_to_milestone": "M8.1.1", "rationale": "operator-grade re-probe"}
  ],
  "evidence": [
    {"claim": "Bundle budget enforced in CI", "evidence_path": "docs/verification/phase-7-bundle.md"}
  ],
  "sign_off": {"subagent": "reviewer-final", "human": "alex@devarno.com 2026-04-29"},
  "summary": "Phase 7 implementation closes with one deferred milestone (M8.1.1) per MR-2."
}
JSON
petrova close_phase kahn-hq --input /tmp/petrova-input.json

After apply

The PR landing closes Phase 7. Open Phase 8 next via start_phase, listing M7.8.2 (or whichever) in friction_carryover.