DaoyuanLi2816 · DaoyuanLi2816 · Jul 30, 2026 · Jul 30, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,11 +6,17 @@ All notable changes to miniVERL are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-07-29
+
+Clarity and defensive-hardening release.
+
 ### Changed
 
 - The generated GPU benchmark figure now reports measured 0% negative controls,
-  separates protocol qualification from the quantitative axis, and distinguishes
-  continuation time from the reusable protocol-teacher preparation cost.
+  scopes its title and strict-success label to the saturated v0.2 calculator
+  task, separates protocol qualification from the quantitative axis, and keeps
+  continuation time distinct from teacher preparation without presenting an
+  unsourced preparation duration.
 - The banner and bilingual onboarding now describe the device-name-agnostic
   single-GPU CUDA path and install CUDA PyTorch before optional training extras.
 - Protocol-v2 prompt examples are generated from each environment's active
@@ -20,6 +26,9 @@ All notable changes to miniVERL are recorded here. The format follows
 
 - Legacy teacher caches can no longer bypass adapter or structural-tokenizer
   identity checks, and cache shard/index publication is crash-safe.
+- Teacher caches persist `entries_per_shard`, allocate after the highest
+  numeric indexed or on-disk shard suffix, and publish a copied pruned index
+  before best-effort orphan cleanup.
 - Tokenizer structural digests ignore source-location metadata, and failed
   model construction cannot leave an orphan partial run directory.
 
@@ -308,7 +317,8 @@ Same-tokenizer only; one trajectory per forward pass; `swap` unavailable for
 quantized models; only Qwen3 and Qwen2 architectures tested; single-seed GPU
 results. The full list is in `docs/limitations.md`.
 
-[Unreleased]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/DaoyuanLi2816/mini-verl/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/DaoyuanLi2816/mini-verl/compare/37781ef0b00f3346d4b7b40fbe4d1c0ce1355063...v0.2.0

diff --git a/CITATION.cff b/CITATION.cff
@@ -2,7 +2,7 @@ cff-version: 1.2.0
 title: "miniVERL: On-policy distillation for tool-using agents on one GPU"
 message: "If you use miniVERL in your work, please cite it as below."
 type: software
-version: 0.2.2
+version: 0.2.3
 date-released: 2026-07-29
 license: Apache-2.0
 repository-code: "https://github.com/DaoyuanLi2816/mini-verl"
@@ -98,4 +98,4 @@ references:
     url: "https://arxiv.org/abs/2603.07079"
     notes: >-
       Motivates recording per-token teacher entropy. Entropy-aware divergence
-      mixing is a roadmap item and is not implemented in miniVERL v0.2.2.
+      mixing is a roadmap item and is not implemented in miniVERL v0.2.3.
diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md
@@ -6,6 +6,20 @@ and what it printed.
 
 Last updated: 2026-07-29.
 
+## v0.2.3 clarity and defensive-hardening release status
+
+| item | current state |
+| --- | --- |
+| integration source | PR [#15](https://github.com/DaoyuanLi2816/mini-verl/pull/15), squash-merged as `3e54ebf9a8501f58cb6a0901d827221aba8792e0` after all ten pull-request checks passed |
+| version transition | the release candidate identifies as `0.2.3`; `CHANGELOG.md`, `CITATION.cff` and the pre-tag checklist agree on `v0.2.3` |
+| cache safety | shard size survives reopen; allocation advances past the highest indexed or on-disk numeric suffix; pruning publishes a copied index before best-effort orphan cleanup, with fault-injection coverage on both failure boundaries |
+| protocol examples | schema-v2 examples come from each active environment `ToolSpec`; calculator, JSON navigation, SQLite and custom-environment round trips pass while protocol v1 remains byte-frozen |
+| presentation | the generated figure scopes claims to the saturated v0.2 calculator task, reports completed controls at 0%, omits the unsourced preparation duration and remains legible at native and README widths |
+| frozen scientific artifact | `benchmarks/results/gpu-calc-hard-equal-update-v2.json` remains byte-identical at SHA-256 `53fc1d4d5b7adee09618d77ad62d4086ba56b78569832d6fc7c3bcd5c2695bbc` |
+| release gates | 1085 non-GPU/non-network tests passed at 87.30% branch coverage; 5 GPU and 3 network tests passed; ruff, mypy, build/twine, Markdown links and generated-artifact comparison passed; PR #15 is green |
+| publication authorization | granted on 2026-07-29; publication will use the tag-only Trusted Publishing workflow, not a long-lived PyPI token |
+| exact blocker | none; create and validate the focused release-metadata PR, then annotate and push `v0.2.3` from its exact merged commit |
+
 ## v0.2.2 single-GPU portability release status
 
 | item | current state |

diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -1,17 +1,17 @@
 # Release checklist
 
-This is the release gate and publication record for `v0.2.2`. A checked item
+This is the release gate and publication record for `v0.2.3`. A checked item
 names an invariant that was exercised on the release source. The tag workflow
 repeated the mechanical gates and refused inconsistent metadata or an
 unchecked pre-tag item. Publication began only after explicit maintainer
 authorization.
 
 ## Version consistency
 
-- [x] `src/miniverl/__init__.py` is `0.2.2`.
-- [x] `CHANGELOG.md` has a dated `## [0.2.2]` section.
+- [x] `src/miniverl/__init__.py` is `0.2.3`.
+- [x] `CHANGELOG.md` has a dated `## [0.2.3]` section.
 - [x] `CITATION.cff` version and release date match.
-- [x] The future annotated tag is exactly `v0.2.2`.
+- [x] The future annotated tag is exactly `v0.2.3`.
 - [x] The package/project name remains `miniverl`.
 
 ## Correctness and lifecycle
@@ -61,7 +61,7 @@ authorization.
 
 ## Packaging and clean installs
 
-- [x] A clean `python -m build` produces one `0.2.1` wheel and one sdist.
+- [x] A clean `python -m build` produces one `0.2.3` wheel and one sdist.
 - [x] `python -m twine check dist/*` passes.
 - [x] The wheel contains the report template and no tests.
 - [x] The sdist contains recipes, tests, docs, license and both READMEs.
@@ -100,16 +100,30 @@ authorization.
 
 ## Trusted publishing readiness
 
-- [x] PyPI reports project `miniverl` and current public version `0.2.1`.
+- [x] PyPI reports project `miniverl` and current public version `0.2.2`.
 - [x] GitHub environment `pypi` exists and has a deployment branch policy.
 - [x] `release.yml` requests `id-token: write`, uses the `pypi` environment and
       publishes only on a tag push.
 - [x] The maintainer registered the pending publisher for
       `DaoyuanLi2816/mini-verl`, workflow `release.yml`, environment `pypi`.
-- [x] The immutable `v0.2.0` and `v0.2.1` tags and public artifacts are unchanged.
+- [x] The immutable `v0.2.0`, `v0.2.1` and `v0.2.2` tags and public artifacts
+      are unchanged.
 
 ## After the tag
 
+To be completed from the public release workflow:
+
+- [ ] Annotated tag `v0.2.3` resolves to the exact validated release commit.
+- [ ] The tag workflow passes metadata, tests, build, OIDC publication, public
+      verification and GitHub Release creation.
+- [ ] Public PyPI hashes and Trusted Publishing attestations match the workflow
+      artifacts, and a clean public core install reports `miniverl 0.2.3`.
+- [ ] The `miniVERL v0.2.3` GitHub Release contains the byte-identical wheel,
+      sdist and `SHA256SUMS`.
+- [ ] Development advances to `0.2.4.dev0`.
+
+## Historical v0.2.2 record
+
 Publication completed on 2026-07-29:
 
 - [x] Annotated tag `v0.2.2` resolves to exact validated commit

diff --git a/src/miniverl/__init__.py b/src/miniverl/__init__.py
@@ -14,6 +14,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.3.dev0"
+__version__ = "0.2.3"
 
 __all__ = ["__version__"]