luca-belli · Oct 21, 2026 · Oct 20, 2026 · Oct 21, 2026
@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ main ]
+    branches: [ main, release/2.1 ]
   pull_request:
-    branches: [ main ]
+    branches: [ main, release/2.1 ]
   workflow_dispatch:
 
 # A new push to a PR cancels that PR's in-flight run; runs on main always finish.

@@ -5,7 +5,7 @@ name: Live Tests
 # PR run would bill every push.
 on:
   push:
-    branches: [ main ]
+    branches: [ main, release/2.1 ]
   schedule:
     # Weekly, Monday 06:00 UTC: catches a provider retiring a model during
     # weeks with no merge to main.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Documentation and development workflow
+
+- **Release 2.1 plan**—[`docs/roadmap.md`](docs/roadmap.md#release-21-plan) lists the steps for 2.1 in dependency order with their PRs: safety net, data contracts, job loop, terminal output, then removing `legacy/`, with the judge-flow rewrite in parallel. They accumulate on a `release/2.1` branch that merges into `main` once, at the 2.1.0 tag, so `main` stays releasable; CI now also runs for `release/2.1`.
+
 ## [v2.0.4](https://github.com/SpringCare/VERA-MH/releases/tag/v2.0.4) \- 2026-10-20
 
 ### Breaking / migration

@@ -4,6 +4,30 @@ Future structural work, in order. [architecture.md](./architecture.md) describes
 
 Smaller items that belong to no phase are in the [Backlog](#backlog).
 
+## Release 2.1 plan
+
+2.1 is built on the **`release/2.1`** branch, so `main` stays releasable, legacy scripts included, until 2.1 ships.
+
+- **PRs for the steps below target `release/2.1`.** It merges into `main` once, when every step is done, and that merge is tagged `v2.1.0`.
+- **Fixes, docs, and changes that break nothing still go to `main`,** so 2.0.x users get them; `main` is merged into `release/2.1` regularly so the two don't drift. A 2.0.x release, if one is needed, is tagged from `main`. [`v2.0.4`](https://github.com/SpringCare/VERA-MH/releases/tag/v2.0.4) is the latest.
+- **CI runs on both branches:** pull requests into either, and pushes to either (which also run the integration layer and the live smoke test).
+- The steps are in dependency order. Each design PR is a draft for discussion and can merge to `main` (docs only); its code follows in separate PRs into `release/2.1`.
+
+| Step | What | PRs | Phase |
+|---|---|---|---|
+| 1. Safety net | Tests that prove a change didn't move scores: golden scoring, scripted judge, replay of a recorded run | [#270](https://github.com/SpringCare/VERA-MH/pull/270) (needs the replay recording) | |
+| 2. Data contracts | What a run records (manifest, run config, run record), then naming, order of events, and folder layout, decided together | [#277](https://github.com/SpringCare/VERA-MH/pull/277), then [#268](https://github.com/SpringCare/VERA-MH/pull/268) + [#276](https://github.com/SpringCare/VERA-MH/pull/276) | [Traceability](#traceability) |
+| 3. Engine | One job loop for generation and judging; the pipeline as a single job list | [#266](https://github.com/SpringCare/VERA-MH/pull/266) | [Shared engine](#shared-engine) |
+| 4. Terminal output | Plain event lines, fail-fast, end summary, and prints moved to logs (any time); the live display (after step 3) | [#271](https://github.com/SpringCare/VERA-MH/pull/271) | [Backlog](#cli-and-run-experience) |
+| 5. Remove `legacy/` | Delete the scripts, their parity tests, and [legacy-scripts.md](./legacy-scripts.md), as announced in v2.0.4 | — | [Deferred](#deferred) |
+| In parallel | A judge flow that decides each outcome once; needs the HFO rubric authors' answer on Q11 | [#267](https://github.com/SpringCare/VERA-MH/pull/267) (after step 1) | [Rubric-agnostic scoring](#rubric-agnostic-scoring) |
+
+- **Why this order.** Step 1 comes first because every later step is meant to leave scores unchanged, and it's what proves that. Step 2 defines the files and folders the job loop in step 3 reads and writes (its resume checks, the run roots it needs up front). Step 4's live display needs the events step 3 emits; its other half needs nothing.
+- **Inside step 2:** first one function that creates run roots, one clock read per run, and the tests that enforce both, still writing today's folder names; then the run record; then the new layout and conversation files. #276 replaces #268's layout section, so the two are settled as one decision.
+- **Removing `legacy/` last** keeps the legacy scripts working through the other steps on `release/2.1` too. Until then the [phase rules](#how-phases-work) still apply: legacy adapts and the domain doesn't bend.
+- **Smaller PRs go to `main`:** [#270](https://github.com/SpringCare/VERA-MH/pull/270) (tests only), [#278](https://github.com/SpringCare/VERA-MH/pull/278) (`vera` command), [#269](https://github.com/SpringCare/VERA-MH/pull/269) (user-side language).
+- **When every step has merged into `release/2.1`:** merge `main` into it one last time, move `[Unreleased]` to `v2.1.0` in the CHANGELOG, merge `release/2.1` into `main`, and tag that merge commit `v2.1.0`.
+
 ## How phases work
 
 - **Phases have names, not numbers.** Code comments and docs cite them by name ("Traceability"), so reordering or inserting a phase never changes what an old reference means.
@@ -131,7 +155,7 @@ Smaller items that belong to no phase. Each can ship as its own PR whenever it's
 
 ## Deferred
 
-- **Removing `legacy/`.** Triggered by a tagged release whose CHANGELOG announces the removal. Then delete `legacy/`, the legacy side of the parity tests, and [legacy-scripts.md](./legacy-scripts.md).
+- **Removing `legacy/`.** Triggered by a tagged release whose CHANGELOG announces the removal; [v2.0.4](https://github.com/SpringCare/VERA-MH/releases/tag/v2.0.4) did. Then delete `legacy/`, the legacy side of the parity tests, and [legacy-scripts.md](./legacy-scripts.md). Scheduled as the last step of the [Release 2.1 plan](#release-21-plan).
 - **Per-persona system prompts.** Personas may need their own system prompts rather than one global prompt. The mechanism (a `system_prompt` field, a `system_prompt_file` pointer, or something else) is undecided; revisit when the persona schema is formalized, likely in [Traceability](#traceability).
 
 ## Completed