chore(ci): pin rivet v0.22.0 (release-handling) + document the readiness gate (#516)

.github/workflows/ci.yml

@@ -187,16 +187,18 @@ jobs:
         uses: actions/cache@v5
         with:
           path: ~/.cargo/bin/rivet
-          key: ${{ runner.os }}-rivet-cli-v0.19.0
+          key: ${{ runner.os }}-rivet-cli-v0.22.0
       # PIN rivet to a release tag (was `--branch main`, unpinned). Unpinned, an
       # upstream schema/behaviour bump silently reddened the gate on unchanged
-      # artifacts (rivet 0.15.0 promoted a WARN→ERROR, #229). v0.19.0 is validated
-      # clean on this repo's artifacts (non-xref ERROR 0, coverage exit 0). Skip
+      # artifacts (rivet 0.15.0 promoted a WARN→ERROR, #229). v0.22.0 (adds the
+      # `rivet release` planning command, #516) is validated clean on this repo's
+      # artifacts before pinning — the exact CI gate below run locally under
+      # v0.22.0 gives non-xref ERROR 0 and coverage exit 0, same as v0.19.0. Skip
       # the (expensive) build entirely on a cache hit.
-      - name: Install rivet (pinned v0.19.0)
+      - name: Install rivet (pinned v0.22.0)
         run: |
-          if ! rivet --version 2>/dev/null | grep -q "0.19.0"; then
-            cargo install --force --git https://github.com/pulseengine/rivet --tag v0.19.0 rivet-cli
+          if ! rivet --version 2>/dev/null | grep -q "0.22.0"; then
+            cargo install --force --git https://github.com/pulseengine/rivet --tag v0.22.0 rivet-cli
           fi
       - name: Validate artifacts
         run: |

docs/release-process.md

@@ -113,6 +113,22 @@ OIDC identity (workflow ref + repo + commit). There is nothing to rotate.
 Before pushing a `v*` tag:
 
 - [ ] All target changes merged to `main`; CI green on the merge commit.
+- [ ] **Release readiness (rivet ≥ v0.22.0, `release` command, #516):** if the
+      release's scope is tracked in rivet via the `release:` field, the burn-down
+      gate is cuttable. Scope artifacts with
+      `rivet modify <ID> --set-release vX.Y.Z` (or re-target with
+      `rivet release move <ID> vX.Y.Z`), then:
+      ```bash
+      rivet release status vX.Y.Z            # ✓ Cuttable / ✗ NOT cuttable + the unverified set
+      rivet release status vX.Y.Z --format json   # machine-readable {cuttable, not_verified, …}
+      ```
+      `rivet release status` exits non-zero while any scoped artifact is not yet
+      `verified`/`accepted`, so it gates cleanly in a script. (synth historically
+      scopes releases with `release-vX.Y.Z` *tags* in `tags:`; the `release:`
+      field is the first-class planning dimension the `release` command reads —
+      adopt it per-release as scope is assigned. CI pins rivet to the validated
+      version; bumping that pin re-runs the `validate`/`coverage` gate first, per
+      the #229 regression lesson.)
 - [ ] `cargo test --workspace` passes locally.
 - [ ] `cargo clippy --workspace --all-targets -- -D warnings` clean.
 - [ ] `cargo fmt --check` clean.