Tracking: release gating — get to a candidate that is verified before v0 moves

One place to watch the release-gating work. The detail lives in PLAN.md (items 0a–0d, added in #137) and in the two design issues; this issue is the sequence, the definition of done, and the current position — it does not duplicate them.

Why this is P0

A release currently reaches a published lecture site before any test has met it. That is the same shape as the alerting item that was P0 before it: the safety net does not do the thing everyone assumes it does.

It also blocks something that is otherwise ready. The lecture family has decided to move to floating @v0 and is sequencing that behind this work (QuantEcon/workspace-lectures#33), because all six of its remaining exact pins sit on publish-gh-pages — the least-gated action in the set.

The finding this rests on

Testing here is in good shape, and better than #100's body suggests — that body predates the harness that answers most of it. test-actions.yml is 15 jobs over four actions, enforced as a required check. test-actions-lecture-intro runs the real chain including publish-gh-pages and preview-netlify.

Coverage is not the problem. Two things are.

First, lead time. The canary leads consumers on one path of three:

Path	Canary trigger	Consumers	Lead
Weekly cache	schedule, Sun 03:00 UTC	Mon 02:00 UTC (lecture-dp), Mon 03:00 UTC (six others)	23–24h
Preview	pull_request in the canary	every PR, every repo	none
Publish	tag push in the canary	tag push per repo	none

Second, and more fundamental: the canary pins @v0, the tag a release moves. So it only ever exercises a published release and cannot test a candidate at all. No change to its triggers fixes that — it is a post-release regression detector by construction.

Definition of done

A bad release cannot reach a published lecture site before it has failed somewhere we are watching. Concretely:

1. a release candidate is exercised end to end before v0 moves;
2. the gate's red is trustworthy — it is not confounded by container drift, dependency drift, or fixture content;
3. the gate has been observed stopping a release, and a red gate has been observed reaching a human;
4. the paths the gate does not cover are named, not assumed away.

Sequence

Each step is independently useful; they are ordered by dependency, not by size.

• 0a — build test-actions-release (#136). The gate needs a fixture whose red is unambiguous, and the existing canary structurally cannot be it: quantecon-build:latest, Dependabot enabled, @v0. The first two are the right properties for a sandbox and disqualifying for a gate, and both are repo-level, so one repo cannot hold both roles. Decided: purpose-built rather than trimmed from intro, container pinned by digest, no build-time network reads, ~5 lectures, all three builders, staged-failure self-test from day one. Must cover plotly/kaleido static export — the #85 path is uncovered by any fixture today
• 0b — add the v0-next staging tag and gate on it (#135). Move v0-next to the candidate → dispatch the gate → require green → move v0. Works because @v0-next is as static as @v0; GitHub forbids expressions in uses:, so no parameterised-ref design exists
• 0c — close the ungated paths regardless of 0b (#135). Schedule the canary's ci.yml and publish.yml ahead of consumers' Monday builds. publish.yml has no workflow_dispatch today, so it cannot even be run by hand. This is the post-release safety net and is worth having whether or not the gate lands
• 0d — prove it (#135). Two separate things: that the gate can stop a release, and that a red gate reaches a human. Both have precedent here — the container smoke tests could not fail and still reported green (#108), and the canary failed eight consecutive weeks filing zero issues (#83)
• Hand back to consumers. The lecture family repins its six call sites — QuantEcon/workspace-lectures#31 section A. Repin the canary first, watch one real build, then the lecture repos

What this will not cover, stated up front

build-jupyter-cache reaches its siblings at a hardcoded @v0 — setup-environment@v0 and build-lectures@v0, four call sites in build-jupyter-cache/action.yml. A @v0-next run therefore exercises the candidate's cache action against the previous release's siblings, and that pairing stays untested until v0 moves.

So "verified green before release" will mean "everything except that chain", and it should be described that way rather than as a blanket guarantee. Two options for closing it are sketched in #135 — rewriting sibling refs to the candidate SHA at release time, or accepting it and leaning on the cache path's existing 23–24 hour lead. Not yet decided.

Also unchanged: real-scale performance and content diversity stay with test-containers-lectures.yml, and the lecture-jax GPU path stays out of scope while QuantEcon/lecture-jax#284 is open.

Open decisions

Question	Blocks
Is the release blocked automatically, or by a documented runbook step? There is no release automation here today — v0 is moved by hand	0b
Who receives a red gate — an issue in this repo, a notification, both?	0d
Is the build-jupyter-cache residual accepted, or worth the ref-rewrite?	scope of the claim

Related

• #135 — gate mechanism and v0-next
• #136 — the gate fixture
• #137 — PLAN.md update carrying items 0a–0d and the corrected consumers table
• #100 — testing; 0a–0d are its stage 4 and the verification it did not specify
• #83, #108 — the two precedents behind 0d
• QuantEcon/workspace-lectures#33 — consumer view; QuantEcon/workspace-lectures#31 — the repin that follows

Start with PLAN.md items 0a–0d and the linked issues #135 and #136. Inspect test-actions.yml, ci.yml, publish.yml, and the four sibling-action references in build-jupyter-cache/action.yml. Done means a candidate is exercised before v0 moves, the gate's failure is trustworthy and observed stopping a release and reaching a human, and uncovered paths are documented.