/ct-release-orchestrator

name: ct-release-orchestrator
description: "Orchestrates the canonical 4-verb release pipeline introduced by SPEC-T9345: cleo release plan, then cleo release open, then PR + GHA tag workflow, then cleo release reconcile. The deprecated cleo release ship monolith was deleted in T10103 — do not invoke it. Use ship-e2e-smoke to validate the full pipeline end-to-end (dry-run by default). The full verb-to-state map is in docs/release/verb-matrix.md. Use when shipping a new version, validating the release pipeline end-to-end, or promoting a completed epic to released status."
protocol: release
adrRefs:
  - ADR-053
  - ADR-063
  - ADR-065
metadata:
  version: 3.2.7
  tier: on-demand
  install: harness
  covers:
    - packages/core/src/validation/protocols/cant/release.cant
    - packages/core/src/validation/protocols/protocols-markdown/release.md
    - packages/cleo/src/cli/commands/release.ts
  loomStage: release
  lastReviewed: 2026-10-16
  stability: stable

Release Orchestrator

Overview

Independent opt-in canaries use `--channel canary` with a numbered `vYYYY.MM.N-canary.N` version. The OIDC workflow publishes this version only to `canary`, verifies registry convergence and soaks the installed package. It never continues to `latest`. Stable promotion is a separate normal release; use `--hooks-v1-promotion` on the stable promotion plan; ordinary releases and hotfixes are exempt. The promotion gate runs before GitHub Release creation. That plan also makes `scripts/mark-hotfix-release.mjs` stamp `cleo.releasedFeatures: ["hooks-v1"]` into `@cleocode/core`, which opens the hooks-v1 runtime gate on the stable build (T13557); stable candidates without it prove the runtime inert. hooks-v1 was promoted in v2026.10.17 and is released in source since T13776 (`UNRELEASED_HOOK_FEATURES` is empty), so later releases need neither the flag nor the stamp. `cleo release plan` refuses a stable plan whose source opens that gate since the previous tag (`hooks-v1` leaving the set, a changed `hooksV1Released`, a deleted gate) with `E_HOOKS_V1_PROMOTION_REQUIRED`, unless it is the promotion or passes `--hooks-v1-waiver "<reason>"`, which the plan and `.cleo/audit/hooks-v1-waiver.jsonl` record (T13555). A release right after the promotion (its committed plan sets `hooksV1Promotion`) is exempt, so the post-promotion removal needs no waiver. The unified-hooks pilot must first supply hosted VidaPeps CI, read-only database verification and live harness evidence bound to the exact canary source digest. Source changes require fresh pilot evidence. Do not move npm tags manually.

Owns the canonical 4-verb release pipeline established by SPEC-T9345 and finalised when T9540 deleted the legacy `start` / `verify` / `publish` verbs (and the 12-step `releaseShip` monolith) plus T10103 deleted the deprecated `ship` shim. The current verb surface is documented in `docs/release/verb-matrix.md` — that file is the SSoT for verb-to-state mapping. This skill is the agent-facing entry point and references the matrix instead of redefining it.

Core Principle

> Each verb owns exactly one state transition. No verb performs more than one mutation. Multi-step orchestration uses `ship-e2e-smoke` (validator) — never compose the verbs into a custom script. The one sanctioned end-to-end runner is `scripts/release-run.mjs` (below).

**Single release PR (T13825, owner choice 2026-10-16).** `node scripts/release-run.mjs <ver> --epic <id> --notes-review <file> [--execute]` runs plan → independent notes review (`{"reviewer","notesSha256","approved":true}` by someone other than the operator, for the plan's exact `meta.releaseNotes`) → `release/plan-<ver>` (one commit, plan + CHANGELOG.md, on the default branch's HEAD, made through the GitHub API) → `cleo release open <ver> --ref release/plan-<ver>` → waits for release-prepare and the bump PR's dispatched `CI` on its exact head → version-only assert against the merge-base → `gh pr merge --admin --merge --match-head-commit` plus the `.cleo/audit/force-bypass.jsonl` line → explicit `git tag -a` on the merge commit and push. The bump PR carries the plan and the bump. Dry-run by default; every step resumes on re-run. `--ref` alone dispatches on any plan branch; preflight skips carry over only when it adds release-plan files alone.

Canonical Pipeline

| Step | Verb / Workflow | Owns transition | Notes | |-----:|------------------|------------------|-------| | 1 | `cleo release plan <ver> --epic <id>` | _(none)_ → `planned` | Builds the Release Plan envelope; auto-writes `CHANGELOG.md` (T10105 closes the silent-skip gap). stdout is the one envelope, and the readiness report goes to stderr (T13322). A `--tasks` plan records `epicId: null`, and each task keeps its own `epicAncestor` (T13323) | | 2 | `cleo release open <ver>` | `planned` → `pr-opened` | Dispatches `release-prepare.yml` with the plan's sha256 once the plan is verified on the default branch, plus the verified preflight skips; the workflow cuts the branch + opens the PR | | 3 | _(GHA)_ `release-prepare.yml` → PR merge | `pr-opened` → `pr-merged` | Owned by CI; verify via `cleo release pr-status <ver>` | | 4 | `git tag -a v<ver> -m "Release v<ver>" && git push origin v<ver>` | `pr-merged` → `tag-pushed` | Explicit tag after the release PR merges — `auto-tag-on-release-merge.yml` is retired (T10434, ADR-087); the tag push triggers `release.yml` | | 5 | `cleo release reconcile <ver>` | `tag-pushed` → `published` | Backfills 11 provenance tables; idempotent | | 6 | _(GHA)_ `release.yml` Publish: release candidate gate | `<ver>-rc.ci.<n>` on `canary` → `<ver>` on `latest` | Automatic, OIDC only, no token (T13181). The candidate must install from npm and pass the sandbox soak (`scripts/release-canary-soak.mjs`) before the release publishes to `latest`; a failed gate leaves users on the previous release, and a re-run of the failed job continues. No dist-tag is ever moved by hand: a bad release is fixed forward with the next patch.