Skip to content

SOP-055 — Release (cut, verify, hand off)

Guide

<!-- last-reviewed: 2026-06-01 · owner: Engineering (Engineering Director) -->

SOP-055 — Release (cut, verify, hand off)

SOP · owner: Engineering (Engineering Director). Layer: SOP/Runbook (docs/canon.md). Ships a reviewed change set as a deliberate, budget-safe release. The Vercel deploy shape is ours; the deploy pipeline (SOP-058) is run by the Platform Engineer; the CI tooling is Operations’.

Interface Contract

  • Inputs: reviewed code change ← from self (Engineering Director, SOP-054) · trigger: review passed
  • Outputs: release / ADR / spec → to Archivist · trigger: artifact approved
  • Outputs: changed intranet/README.md / architecture note → to Documentarian · trigger: document changed
  • Outputs: dependency added/removed/changed → to Legal Director · trigger: dependency changed
  • Outputs: release handed for independent review → to Quality & Risk · trigger: review requested
  • Handoff trigger (in): a change set has passed code review (SOP-054) and is ready to ship
  • Handoff trigger (out): the release is cut, build-verified, and its artifacts are preserved
  • Definition of Done before handoff:
    • [ ] All changes in the set passed SOP-054 (review passed)
    • [ ] cd intranet && npm run build green at the release commit (~50 pages, [sync] …)
    • [ ] Push batched to a deliberate checkpoint (GR-7) — not per-commit (ADR-0009, 100/day)
    • [ ] Deploy verified per SOP-058 (build log, auth gate)
    • [ ] ADRs / specs handed to the Archivist (artifact approved)
    • [ ] Dependency changes flagged to Legal (dependency changed); doc changes to Documentarian (document changed)
    • [ ] Learnings captured to docs/knowledge/ if the release surfaced one

All trigger phrases are drawn from docs/handoff-triggers.md. dependency changed and requirements issued are the Engineering↔Legal seam (Wave 1 additions). The artifact approved → Archivist edge is absorbed by the Archivist’s fan-in sink (interface-contract-spec.md §3.1 R1).

Purpose

Turn a reviewed change set into a shipped, verified, preserved release without burning the deploy budget or dropping a downstream notification.

When to use

When a change set has passed code review (SOP-054) and is ready to ship — at a deliberate session/milestone checkpoint, never per micro-commit.

Flow

flowchart LR
  A["review passed"] --> B["Build green<br/>at release commit"]
  B --> C["Batch push to main<br/>(checkpoint, GR-7)"]
  C --> D["Verify deploy<br/>(SOP-058)"]
  D --> E["Hand off: Archivist<br/>+ Legal + Documentarian"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  class A,B,C,D,E s

Text fallback: a reviewed change set (review passed) → confirm the build is green at the release commit → batch-push to main at a deliberate checkpoint (GR-7) → verify the Vercel deploy (SOP-058) → hand the ADRs/specs to the Archivist (artifact approved), flag any dependency change to Legal (dependency changed), and notify the Documentarian of doc changes (document changed).

Steps

  1. Confirm review. Every change in the set carries a review passed (SOP-054).
  2. Build at the release commit. cd intranet && npm run build → green, ~50 pages.
  3. Batch the push (GR-7). Promote to main once per checkpoint — each push is a Vercel deploy against the 100/day ceiling (ADR-0009). Commit freely, push deliberately.
  4. Verify the deploy per SOP-058 (build log shows the sync line + page count; the site shows the Vercel auth interstitial unauthenticated, ADR-0008).
  5. Hand off artifacts. ADRs/specs → Archivist (artifact approved). If a dependency was added/removed/changed → Legal Director (dependency changed) for a license re-audit. If intranet/README.md or an architecture note changed → Documentarian (document changed).
  6. Independent review where warranted → hand the release to Q&R (review requested).
  7. Capture learnings to docs/knowledge/ if the release surfaced one.

Roles / approvers

Run by the Engineering Director. Deploy execution + verification by the Platform Engineer (SOP-058). Push timing follows GR-7 / ADR-0009.

Guardrails

  • Never push mid-task (GR-7); each main push deploys and consumes budget.
  • No secrets in the bundle (security.md); spot-check dist for PA personal info.
  • Pipeline tooling is Operations’ — propose CI changes to the Process Engineer.
  • Do not restate SOP-003 here — link to it.

Job aid: deploy steps in docs/units/engineering/job-aids/JA-058-deploy-intranet-steps.md (Platform Engineer). See also: docs/units/engineering/manuals/engineering-director.md · SOP-054 · SOP-058 · docs/sop/deploy-intranet.md (SOP-003) · ADR-0008 / ADR-0009 · docs/handoff-triggers.md.