From daceb26ee7c04e84d350f10480ad93a2e51d5904 Mon Sep 17 00:00:00 2001 From: Luca Belli <129434630+sator-labs@users.noreply.github.com> Date: Tue, 20 Oct 2026 15:48:34 -0700 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20roadmap=20=E2=80=94=20the=20Release?= =?UTF-8?q?=202.1=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lists the 2.1 steps in dependency order with their PRs: safety net (#270), data contracts (#277, then #268 + #276), engine (#266), terminal output (#271), and removing legacy/ last, with the judge flow (#267) in parallel. Each merges into main as it's ready; 2.1.0 is tagged once at the end, and v2.0.4 is the fallback. The Deferred entry for removing legacy/ now notes that v2.0.4 announced it and points to the plan. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++++ docs/roadmap.md | 21 ++++++++++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9378ebbe..0ddb11e4 100644 --- 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. `main` accumulates them and is tagged once at the end; `v2.0.4` is the fallback. + ## [v2.0.4](https://github.com/SpringCare/VERA-MH/releases/tag/v2.0.4) \- 2026-10-20 ### Breaking / migration diff --git a/docs/roadmap.md b/docs/roadmap.md index 1eda73f5..95903f18 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -4,6 +4,25 @@ 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 lands everything below, then is tagged once. Each step merges into `main` as it's ready, so `main` is "2.1 in progress" and [`v2.0.4`](https://github.com/SpringCare/VERA-MH/releases/tag/v2.0.4) is the release to fall back to; a 2.0.x fix, if one is needed, goes on a branch cut from that tag. The steps are in dependency order. Each design PR is a draft for discussion, and its code follows in separate PRs. + +| 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. Until then the [phase rules](#how-phases-work) still apply: legacy adapts and the domain doesn't bend. +- **Smaller PRs fit anywhere:** [#278](https://github.com/SpringCare/VERA-MH/pull/278) (`vera` command), [#269](https://github.com/SpringCare/VERA-MH/pull/269) (user-side language), [#274](https://github.com/SpringCare/VERA-MH/pull/274) (creating an evaluation). +- **When every step has merged,** move `[Unreleased]` to `v2.1.0` in the CHANGELOG and tag it. + ## 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 +150,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 From e1553874d28bac9d71ae5fd9706f91503e6e6d75 Mon Sep 17 00:00:00 2001 From: Luca Belli <129434630+sator-labs@users.noreply.github.com> Date: Wed, 21 Oct 2026 15:28:02 -0700 Subject: [PATCH 2/2] docs, ci: build 2.1 on a release/2.1 branch So main stays releasable, legacy scripts included, until 2.1 ships: the 2.1 steps target release/2.1, which merges into main once at the v2.1.0 tag; fixes, docs, and non-breaking changes keep going to main and are merged into release/2.1 regularly. ci.yml and live.yml now run for release/2.1 as well as main (pull requests into it and pushes to it). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 4 ++-- .github/workflows/live.yml | 2 +- CHANGELOG.md | 2 +- docs/roadmap.md | 13 +++++++++---- 4 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 17695bd5..cd7e79a5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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. diff --git a/.github/workflows/live.yml b/.github/workflows/live.yml index 8d5f066c..206d0d66 100644 --- a/.github/workflows/live.yml +++ b/.github/workflows/live.yml @@ -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 index 0ddb11e4..316fbee5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ### 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. `main` accumulates them and is tagged once at the end; `v2.0.4` is the fallback. +- **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 diff --git a/docs/roadmap.md b/docs/roadmap.md index 95903f18..8d08cf58 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -6,7 +6,12 @@ Smaller items that belong to no phase are in the [Backlog](#backlog). ## Release 2.1 plan -2.1 lands everything below, then is tagged once. Each step merges into `main` as it's ready, so `main` is "2.1 in progress" and [`v2.0.4`](https://github.com/SpringCare/VERA-MH/releases/tag/v2.0.4) is the release to fall back to; a 2.0.x fix, if one is needed, goes on a branch cut from that tag. The steps are in dependency order. Each design PR is a draft for discussion, and its code follows in separate PRs. +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 | |---|---|---|---| @@ -19,9 +24,9 @@ Smaller items that belong to no phase are in the [Backlog](#backlog). - **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. Until then the [phase rules](#how-phases-work) still apply: legacy adapts and the domain doesn't bend. -- **Smaller PRs fit anywhere:** [#278](https://github.com/SpringCare/VERA-MH/pull/278) (`vera` command), [#269](https://github.com/SpringCare/VERA-MH/pull/269) (user-side language), [#274](https://github.com/SpringCare/VERA-MH/pull/274) (creating an evaluation). -- **When every step has merged,** move `[Unreleased]` to `v2.1.0` in the CHANGELOG and tag it. +- **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