diff --git a/docs/developer/guides/branching-strategy.md b/docs/developer/guides/branching-strategy.md
index e538b4bd..6d332361 100644
--- a/docs/developer/guides/branching-strategy.md
+++ b/docs/developer/guides/branching-strategy.md
@@ -33,6 +33,10 @@ feature/Z ────────────────────┘
 ### `main` — stable releases
 
 - Receives merges from `development` at release time (quarterly, or when ready).
+  The quarterly merge brings over the **whole** stable state of `development` —
+  it is *not* a surgical cherry-pick of one feature. Which features are *announced
+  as working* is decided by the release notes, not by branch surgery
+  (see [Maturity-gated promotion](#maturity-gated-promotion) below).
 - Critical bug fixes are cherry-picked from `development` between releases.
 - Every merge is tagged: `v3.0.0`, `v3.0.1` (patch), `v3.1.0` (quarterly).
 - Binder launcher tracks the latest release tag.
@@ -118,6 +122,28 @@ Bug found
 
 Version numbers are managed by setuptools-scm from git tags — see `version-management.md`.
 
+### Maturity-gated promotion
+
+The quarterly `development → main` merge brings over everything stable on
+`development`. The hard part is not *which commits* move — it is being able to say
+"feature X is released and **works**" without claiming the same for half-finished
+work that rode along.
+
+The project solves this with **release notes, not branch surgery**. A declarative
+manifest (`docs/release-notes/feature-manifest.yaml`) lists each shippable feature
+and the tests that validate it. At release time a gate runs each feature's tests
+and sorts it into:
+
+- **Supported (validated)** — `tier_a`/`tier_b` tests pass; guaranteed.
+- **Preview (present, unguaranteed)** — code is on `main` but not guaranteed.
+
+So the MMPDE mover's code can be on `main` while the release announces only the
+validated features as supported — the mover stays "preview" until its validation
+is trusted. Run the gate any time with `./uw dev release-check`, and drive the
+whole promotion with `./uw dev release`.
+
+**Full guide**: `release-process.md`.
+
 ## CI Requirements
 
 For this strategy to work, CI must be reliable:
diff --git a/docs/developer/guides/release-process.md b/docs/developer/guides/release-process.md
new file mode 100644
index 00000000..8eb7d524
--- /dev/null
+++ b/docs/developer/guides/release-process.md
@@ -0,0 +1,193 @@
+# Release Process: Maturity-Gated Quarterly Promotion
+
+**Status**: Active
+**Date**: 2026-06
+
+This guide describes how finished work is promoted from `development` to `main`
+*with confidence*. It complements `branching-strategy.md` (which covers how work
+lands on `development` in the first place) and `version-management.md` (tags and
+versioning).
+
+## Overview — the "we can be sure it works" guarantee
+
+`development` is a busy integration trunk — at any time it is hundreds of commits
+ahead of `main` and carries many features at different stages of maturity. The
+goal is **not** to surgically isolate one feature's commits onto `main`. That
+fights the grain: a feature like the MMPDE mover depends on the Winslow smoother,
+boundary-slip surfaces, FMG infrastructure, and field-transfer — its dependency
+closure is most of `development` anyway.
+
+Instead:
+
+> `main` accumulates whatever stable work comes over from `development` each
+> quarter. The **release notes** — not branch surgery — distinguish features that
+> are *validated and guaranteed* from features that are merely *present but not
+> guaranteed to work*.
+
+So the mover's code can be on `main` while the release simply does **not** claim
+it works. FMG can be announced as supported while the mover rides along as
+preview. This matches how the project actually develops.
+
+## Maturity definitions
+
+Every shippable feature is announced at one of three maturities:
+
+| Maturity | Meaning | Release-notes section |
+|----------|---------|-----------------------|
+| **supported** | `tier_a`/`tier_b` tests exist and pass on the release candidate. Guaranteed to work. | *Supported (validated)* |
+| **preview** | Code is on `main`, but the release does **not** guarantee it works. | *Preview (present, unguaranteed)* |
+| **experimental** | Present in the tree, not announced as working. | *Preview* (tagged `experimental`) |
+
+The announced maturity is `min(claim, tests_maturity)`:
+
+- An owner may be deliberately **cautious** — claim `preview` even though the
+  tests pass (this is the mover today).
+- The gate may **downgrade** — claim `supported` but a test fails, or there is no
+  validation suite, so it drops to `preview`/`experimental`.
+
+The gate **never blocks the `development → main` merge**. The code ships
+regardless; only the announcement changes.
+
+## The feature manifest
+
+Features are declared in **`docs/release-notes/feature-manifest.yaml`**. Each
+entry scopes *which tests belong to a feature*; the existing tier markers scope
+*which of those tests are trustworthy*. There is **no per-feature pytest marker**
+to maintain.
+
+```yaml
+features:
+  - key: units-system
+    title: "Units and Scaling System"
+    owner: "@lmoresi"
+    claim: supported                 # what the owner wants to announce
+    summary: >
+      Pint-backed dimensional quantities and unit-aware arithmetic.
+    validation:
+      paths:                          # test files/globs that scope the feature
+        - tests/test_0700_units_system.py
+        - tests/test_0710_units_utilities.py
+      select: "..."                   # optional pytest -k to narrow
+      markers: "tier_a or tier_b"     # default; ties "supported" to validated tiers
+      levels: "1,2,3"                 # optional level filter (cost control)
+    docs:
+      - docs/developer/design/UNITS_SIMPLIFIED_DESIGN_2025-11.md
+```
+
+### Worked example: FMG vs the mover
+
+- **FMG** claims `supported` but has **no dedicated `tier_a` test** yet. The gate
+  finds an empty selection and downgrades it to `experimental`. That is the
+  signal you want: *FMG cannot be announced as supported until it has a
+  validation suite.* Add a `tier_a` test and the row goes green.
+- **The MMPDE mover** has passing `tier_a` tests, but its owner claims `preview`
+  because it is not yet trusted across production problems. It announces as
+  `preview` — code on `main`, not guaranteed. This is the canonical case.
+
+## The validation gate
+
+`scripts/release_gate.py` reads the manifest and, per feature, builds a pytest
+invocation equivalent to:
+
+```bash
+pytest --config-file=tests/pytest.ini <expanded paths> \
+       -m "(tier_a or tier_b) and (level_1 or level_2 or level_3)" \
+       -k "<select>"
+```
+
+It then resolves `tests_maturity` from the result:
+
+- non-empty selection under `tier_a or tier_b` **and** all pass → `supported`
+- tests ran but some failed → `preview`
+- empty selection (no `tier_a`/`tier_b` tests — e.g. only `tier_c`), all selected
+  tests skipped, no tests at all, or a pytest execution error → `experimental`
+
+"Supported" is therefore tied to the validated tiers *by construction* — you
+cannot announce a feature as supported without `tier_a`/`tier_b` tests that pass.
+
+Run it any time (intended on `development`):
+
+```bash
+./uw dev release-check          # quick dry-run, levels 1,2
+./uw dev release-check 1,2,3    # full
+```
+
+## Quarterly checklist
+
+Run `./uw dev release` from the **main checkout on `development`**. Every
+state-changing step is confirmed; the tool stops **before** the production tag so
+`main`'s branch protection (PR + review) stays intact.
+
+| # | Step | Automated? |
+|---|------|------------|
+| 1 | Preflight: on `development`, clean tree, fetched, ahead of `main` | auto |
+| 2 | Pick the next version (`vX.Y.0`) | confirm |
+| 3 | Tag + push the RC on `development` (`vX.Y.0rcN`) — RC tags are allowed here | confirm |
+| 4 | Full validation: `test_levels.sh 1,2,3 --isolation` + the per-feature gate | auto |
+| 5 | Aggregate results → achieved maturity per feature (results to `$TMPDIR`) | auto |
+| 6 | Scaffold `docs/release-notes/vX.Y.0.md` with auto Supported / Preview sections | confirm |
+| 7 | Open the `development → main` PR with the rendered notes | confirm |
+| 8 | **After the PR merges**: `git tag vX.Y.0 && git push` → CI publishes the release | manual |
+
+Step 8 is deliberately left to a human so the review gate on `main` is never
+bypassed. CI (`.github/workflows/release.yml`) publishes the GitHub Release from
+the committed `docs/release-notes/vX.Y.0.md`.
+
+## Release notes generation
+
+Steps 4–6 auto-populate two sections of the notes from the gate:
+
+- **Supported (validated)** — features whose achieved maturity is `supported`.
+- **Preview (present, unguaranteed)** — everything else that is announced
+  (`preview`, and `experimental` tagged as such).
+
+You then hand-write **Highlights** and **Contributors**. The template lives at
+`docs/release-notes/TEMPLATE.md`.
+
+## Branch hygiene
+
+The other half of staying organised is not letting merged branches pile up. Run
+before each release (or whenever the branch list feels tangled):
+
+```bash
+./uw dev branch-hygiene            # report: merged / open-PR / stale
+./uw dev branch-hygiene --prune    # delete merged branches (confirms each)
+```
+
+It lists branches merged into `development` (safe to delete), branches with open
+PRs (never pruned), and stale branches (unmerged, no PR, >90 days). `--prune`
+deletes only merged-and-no-open-PR branches, confirming each.
+
+## Knowing what's available to release
+
+Before a release, find out which features have actually landed on `development`
+since the last one — the pool you can choose to announce:
+
+```bash
+./uw dev feature-audit              # feature-branch PR merges since last release
+./uw dev feature-audit --all        # also include bugfix/ and docs/ merges
+./uw dev feature-audit --since v3.0.1
+```
+
+It lists each merged `feature/*` PR (date, number, branch) and reminds you how
+many features the manifest currently declares. Use it to decide which merges
+become manifest entries (and at what maturity) for the upcoming release. It
+detects PR-*merge* commits only — squash-merged PRs won't appear.
+
+This is the feature-level counterpart to the test-level drift check below:
+`feature-audit` answers "what merged that we might announce", while
+`check_manifest_coverage.py` answers "what validated test isn't claimed".
+
+## Keeping the manifest honest
+
+The main risk is **drift** — a `tier_a` test file that no feature references, so
+its coverage is invisible to the gate. `scripts/check_manifest_coverage.py` (run
+in `development` CI) warns when a `tier_a`-marked test file is not referenced by
+any feature's `validation.paths`. Start as a warning; promote to an error once
+coverage is established.
+
+## See also
+
+- `docs/developer/guides/branching-strategy.md` — how work lands on `development`
+- `docs/developer/guides/version-management.md` — tags and `setuptools-scm`
+- `docs/developer/TESTING-RELIABILITY-SYSTEM.md` — the tier A/B/C system
diff --git a/docs/release-notes/TEMPLATE.md b/docs/release-notes/TEMPLATE.md
index 60e87cc9..0aa00a38 100644
--- a/docs/release-notes/TEMPLATE.md
+++ b/docs/release-notes/TEMPLATE.md
@@ -7,6 +7,16 @@
 
 - Brief summary of the most important changes in this release.
 
+## Supported (validated)
+
+<!-- Auto-populated by scripts/release_gate.py from the feature manifest:
+     features whose tier_a/b validation passed on this release. Guaranteed. -->
+
+## Preview (present, unguaranteed)
+
+<!-- Auto-populated: features whose code is on main but is NOT guaranteed to work.
+     See docs/developer/guides/release-process.md for what these labels mean. -->
+
 ## New Features
 
 - Feature description (PR #NN)
diff --git a/docs/release-notes/feature-manifest.yaml b/docs/release-notes/feature-manifest.yaml
new file mode 100644
index 00000000..b15d14a1
--- /dev/null
+++ b/docs/release-notes/feature-manifest.yaml
@@ -0,0 +1,107 @@
+# Underworld3 feature manifest
+# =============================
+# Declarative registry of shippable features for maturity-gated releases.
+#
+# At release time (and any time via `./uw dev release-check`), scripts/release_gate.py
+# runs each feature's `validation` selection against the current checkout and
+# decides whether the feature can be ANNOUNCED at the maturity its owner claims:
+#
+#   supported    — tier_a/b tests exist and pass on the release candidate. Guaranteed.
+#   preview      — code is on main, but the release does NOT guarantee it works.
+#   experimental — present, not announced as working.
+#
+# The announced maturity is min(claim, tests_maturity):
+#   * an owner may be deliberately cautious (claim `preview` even though tests pass);
+#   * the gate may downgrade (claim `supported` but a test fails -> preview).
+# It NEVER blocks the dev->main merge — the code ships regardless; only the
+# announcement in the release notes changes.
+#
+# "Supported" is tied to the existing tier markers by construction: a feature's
+# selection is filtered to `tier_a or tier_b` (see validation.markers), so
+# passing == validated. There is NO per-feature pytest marker to maintain — the
+# manifest scopes WHICH tests belong to a feature; the tier markers scope WHICH
+# are trustworthy.
+#
+# Full guide: docs/developer/guides/release-process.md
+#
+# Schema (per feature):
+#   key:     stable slug (used in tool output and the drift check)
+#   title:   human title for the release notes
+#   owner:   GitHub handle of the person who vouches for it
+#   claim:   supported | preview | experimental  (what the owner wants to announce)
+#   summary: one-line description for the release notes
+#   validation:
+#     paths:   list of test files/globs that scope the feature (required to be announceable)
+#     select:  optional pytest -k expression to narrow within those files
+#     markers: marker expression; defaults to "tier_a or tier_b" — leave as default
+#              unless you have a good reason
+#     levels:  optional "1,2,3" level filter for cost control (per-feature override)
+#   docs:    optional list of doc pages describing the feature
+
+schema_version: 1
+
+features:
+  - key: units-system
+    title: "Units and Scaling System"
+    owner: "@lmoresi"
+    claim: supported
+    summary: >
+      Pint-backed dimensional quantities, non-dimensionalisation, and unit-aware
+      expression arithmetic.
+    validation:
+      paths:
+        - tests/test_0700_units_system.py
+        - tests/test_0710_units_utilities.py
+        - tests/test_0751_subtraction_chain_units.py
+        - tests/test_0752_units_scale_factor_preservation.py
+        - tests/test_0754_arithmetic_closure_complete.py
+      markers: "tier_a or tier_b"
+    docs:
+      - docs/developer/design/UNITS_SIMPLIFIED_DESIGN_2025-11.md
+
+  - key: mesh-smoothing
+    title: "Winslow Mesh Smoother"
+    owner: "@lmoresi"
+    claim: supported
+    summary: >
+      Parallel-safe interior mesh smoothing (smooth_mesh_interior) — the
+      foundation the adaptive movers and geometric multigrid build on.
+    validation:
+      paths:
+        - tests/test_0850_mesh_smoothing.py
+      markers: "tier_a or tier_b"
+
+  - key: mesh-adaptation
+    title: "MMPDE Mesh Mover / Adaptive Remeshing"
+    owner: "@lmoresi"
+    # Claimed `preview` on purpose: the tier_a tests below pass, but we are not
+    # yet ready to GUARANTEE the mover across production problems. The gate will
+    # show tests-pass but announce it as preview (min(claim, tests) == preview).
+    # This is the canonical "code is on main but unguaranteed" case.
+    claim: preview
+    summary: >
+      follow_metric / OT mesh movement and variable transfer for anisotropic
+      mesh adaptation.
+    validation:
+      paths:
+        - tests/test_0750_meshing_follow_metric.py
+        - tests/test_0760_mesh_ot_adapt.py
+        - tests/test_0830_mesh_adapt_variable_transfer.py
+      markers: "tier_a or tier_b"
+
+  - key: fmg
+    title: "Geometric Multigrid / FMG Preconditioner"
+    owner: "@lmoresi"
+    # Claimed `supported`, but there is no dedicated tier_a/b validation suite
+    # yet. The gate will report an empty selection and DOWNGRADE this to
+    # experimental — exactly the signal we want: FMG cannot be announced as
+    # supported until it has a tier_a test. Add one, then this row goes green.
+    claim: supported
+    summary: >
+      Automatic geometric full-multigrid preconditioning for the SNES solvers
+      on refinement meshes (the `preconditioner` property).
+    validation:
+      paths:
+        - tests/test_101*.py
+      select: "multigrid or fmg or preconditioner"
+      markers: "tier_a or tier_b"
diff --git a/scripts/check_manifest_coverage.py b/scripts/check_manifest_coverage.py
new file mode 100755
index 00000000..b754565a
--- /dev/null
+++ b/scripts/check_manifest_coverage.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Manifest coverage check for the release gate.
+
+Guards against *manifest drift*: a tier_a-marked test file that no feature in
+docs/release-notes/feature-manifest.yaml references, so its coverage is invisible
+to the release gate (scripts/release_gate.py).
+
+Every tier_a test file should belong to some feature's validation.paths. This
+script reports any that do not.
+
+Usage:
+    python scripts/check_manifest_coverage.py          # warn-only (exit 0)
+    python scripts/check_manifest_coverage.py --strict # exit 1 if any uncovered
+
+Intended to run in development CI as a warning first, promoted to --strict once
+coverage is established. Standard library + PyYAML only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import re
+import sys
+
+try:
+    import yaml
+except ImportError:
+    sys.stderr.write("error: PyYAML not found. Run via the pixi env.\n")
+    sys.exit(2)
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+MANIFEST = os.path.join(REPO_ROOT, "docs", "release-notes", "feature-manifest.yaml")
+TESTS_DIR = os.path.join(REPO_ROOT, "tests")
+
+# Match @pytest.mark.tier_a or pytestmark = [... tier_a ...]
+TIER_A_RE = re.compile(r"\btier_a\b")
+
+
+def tier_a_files() -> set[str]:
+    """Repo-relative paths of test files that reference tier_a."""
+    found = set()
+    for path in glob.glob(os.path.join(TESTS_DIR, "**", "test_*.py"), recursive=True):
+        try:
+            with open(path, encoding="utf-8") as fh:
+                if TIER_A_RE.search(fh.read()):
+                    found.add(os.path.relpath(path, REPO_ROOT))
+        except OSError:
+            continue
+    return found
+
+
+def manifest_covered_files() -> set[str]:
+    """Repo-relative test paths referenced by any feature's validation.paths."""
+    with open(MANIFEST) as fh:
+        data = yaml.safe_load(fh) or {}
+    covered = set()
+    for feat in data.get("features", []):
+        for pat in (feat.get("validation", {}) or {}).get("paths", []) or []:
+            for hit in glob.glob(os.path.join(REPO_ROOT, pat), recursive=True):
+                covered.add(os.path.relpath(hit, REPO_ROOT))
+    return covered
+
+
+def main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description="Check release-manifest coverage of tier_a tests")
+    ap.add_argument("--strict", action="store_true", help="exit non-zero if any tier_a file is uncovered")
+    args = ap.parse_args(argv)
+
+    tier_a = tier_a_files()
+    covered = manifest_covered_files()
+    uncovered = sorted(tier_a - covered)
+
+    print(f"tier_a test files:        {len(tier_a)}")
+    print(f"referenced by manifest:   {len(tier_a & covered)}")
+    print(f"uncovered:                {len(uncovered)}")
+
+    if uncovered:
+        print("\nThe following tier_a test files are not referenced by any feature")
+        print("in docs/release-notes/feature-manifest.yaml — their coverage is")
+        print("invisible to the release gate. Add them to a feature's validation.paths:")
+        for f in uncovered:
+            print(f"  - {f}")
+        if args.strict:
+            return 1
+        print("\n(warning only; re-run with --strict to fail CI)")
+    else:
+        print("\nAll tier_a test files are covered by the manifest.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/scripts/release_gate.py b/scripts/release_gate.py
new file mode 100755
index 00000000..28246aad
--- /dev/null
+++ b/scripts/release_gate.py
@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""Release validation gate for Underworld3.
+
+Reads the feature manifest (docs/release-notes/feature-manifest.yaml) and, for
+each shippable feature, runs its declared test selection against the *current*
+checkout. The result decides whether the feature can be *announced* at the
+maturity its owner claims.
+
+The model (see docs/developer/guides/release-process.md):
+
+  * `main` accumulates whatever stable work comes over from `development`.
+  * A release ANNOUNCES features at one of three maturities:
+        supported    — validated; tier_a/b tests exist and pass. Guaranteed.
+        preview      — present on main, but not guaranteed to work.
+        experimental — present, not announced as working.
+  * The announced maturity is min(claim, tests_maturity): an owner may be
+    cautious (claim preview even though tests pass), and the gate may downgrade
+    (claim supported but a test fails -> preview). It NEVER blocks the merge —
+    the code ships regardless; only the announcement changes.
+
+"Supported" is tied to the existing tier markers by construction: a feature's
+selection is filtered to `tier_a or tier_b`, so passing == validated.
+
+Subcommands:
+  report        Run the gate and print a human-readable table (dry-run).
+  run           Run the gate and emit results as JSON (for tooling).
+  render-notes  Emit the Supported/Preview release-notes sections for a version.
+
+This script uses only the standard library plus PyYAML (already a dependency).
+It shells out to `python -m pytest`, so it must run inside the pixi env, e.g.
+    pixi run -e <env> python scripts/release_gate.py report
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+
+try:
+    import yaml
+except ImportError:  # pragma: no cover - guidance for the rare missing-dep case
+    sys.stderr.write(
+        "error: PyYAML not found. Run this via the pixi env:\n"
+        "  pixi run -e <env> python scripts/release_gate.py ...\n"
+    )
+    sys.exit(2)
+
+# Repo root is the parent of scripts/
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DEFAULT_MANIFEST = os.path.join(REPO_ROOT, "docs", "release-notes", "feature-manifest.yaml")
+PYTEST_CONFIG = os.path.join("tests", "pytest.ini")
+
+# Maturity ordering (higher == more trustworthy)
+MATURITY = {"experimental": 0, "preview": 1, "supported": 2}
+MATURITY_NAME = {v: k for k, v in MATURITY.items()}
+
+
+def _min_maturity(a: str, b: str) -> str:
+    return MATURITY_NAME[min(MATURITY[a], MATURITY[b])]
+
+
+def load_manifest(path: str) -> list[dict]:
+    with open(path) as fh:
+        data = yaml.safe_load(fh) or {}
+    features = data.get("features", [])
+    if not isinstance(features, list):
+        raise ValueError(f"{path}: 'features' must be a list")
+    return features
+
+
+def _expand_paths(paths: list[str]) -> list[str]:
+    """Expand globs relative to the repo root. Returns repo-relative paths."""
+    matched: list[str] = []
+    for pat in paths:
+        hits = glob.glob(os.path.join(REPO_ROOT, pat), recursive=True)
+        for h in sorted(hits):
+            matched.append(os.path.relpath(h, REPO_ROOT))
+    return matched
+
+
+def _marker_expr(markers: str, levels: str | None) -> str:
+    """Combine the feature's marker expression with an optional level filter.
+
+    `levels` is a comma list like "1,2,3" -> "(level_1 or level_2 or level_3)".
+    The marker expression is always applied, so "supported" stays tied to the
+    tier_a/b markers no matter how levels narrow the run.
+    """
+    expr = f"({markers})"
+    if levels:
+        level_terms = " or ".join(f"level_{n.strip()}" for n in levels.split(",") if n.strip())
+        if level_terms:
+            expr = f"{expr} and ({level_terms})"
+    return expr
+
+
+def _run_feature(feature: dict, cli_levels: str | None) -> dict:
+    """Run one feature's test selection and resolve its maturity."""
+    key = feature.get("key", "?")
+    claim = feature.get("claim", "experimental")
+    if claim not in MATURITY:
+        raise ValueError(f"feature '{key}': invalid claim '{claim}'")
+
+    val = feature.get("validation", {}) or {}
+    paths = _expand_paths(val.get("paths", []) or [])
+    markers = val.get("markers", "tier_a or tier_b")
+    select = val.get("select")
+    # Per-feature levels override the CLI default; both are optional.
+    levels = val.get("levels", cli_levels)
+
+    result = {
+        "key": key,
+        "title": feature.get("title", key),
+        "owner": feature.get("owner", ""),
+        "claim": claim,
+        "summary": (feature.get("summary") or "").strip(),
+        "n_selected": 0,
+        "n_passed": 0,
+        "n_failed": 0,
+        "n_skipped": 0,
+        "tests_maturity": "experimental",
+        "announced": "experimental",
+        "verdict": "ok",
+        "note": "",
+    }
+
+    if not paths:
+        result["note"] = "no test files matched validation.paths"
+        result["announced"] = _min_maturity(claim, "experimental")
+        result["verdict"] = "downgraded" if claim != "experimental" else "ok"
+        return result
+
+    marker_expr = _marker_expr(markers, levels)
+
+    with tempfile.NamedTemporaryFile(suffix=".xml", delete=False) as tf:
+        junit_path = tf.name
+    try:
+        cmd = [
+            sys.executable, "-m", "pytest",
+            f"--config-file={PYTEST_CONFIG}",
+            "-q", "-p", "no:cacheprovider",
+            "--timeout=300",
+            f"--junit-xml={junit_path}",
+            "-m", marker_expr,
+        ]
+        if select:
+            cmd += ["-k", select]
+        cmd += paths
+
+        env = dict(os.environ)
+        env.setdefault("UW_ENABLE_TELEMETRY", "0")
+        proc = subprocess.run(cmd, cwd=REPO_ROOT, env=env,
+                              capture_output=True, text=True)
+
+        # pytest exit codes: 0=passed, 1=failed, 2=interrupted, 3=internal
+        # error, 4=usage error, 5=no tests collected.
+        if proc.returncode == 5:
+            result["note"] = "selection is empty under tier_a/b markers"
+            result["tests_maturity"] = "experimental"
+        elif proc.returncode not in (0, 1):
+            # The gate could not run this feature's tests, so we cannot validate
+            # it — never call it supported, and flag the error loudly rather than
+            # silently reporting "experimental/skipped".
+            result["tests_maturity"] = "experimental"
+            tail = (proc.stderr or proc.stdout or "").strip().splitlines()
+            hint = f": {tail[-1]}" if tail else ""
+            result["note"] = f"pytest execution error (exit {proc.returncode}){hint}"
+        else:
+            counts = _parse_junit(junit_path)
+            result.update(counts)
+            n_real = counts["n_selected"] - counts["n_skipped"]
+            if n_real <= 0:
+                result["tests_maturity"] = "experimental"
+                result["note"] = "all selected tests skipped"
+            elif counts["n_failed"] > 0:
+                result["tests_maturity"] = "preview"
+                result["note"] = f"{counts['n_failed']} test(s) failed"
+            else:
+                result["tests_maturity"] = "supported"
+    finally:
+        try:
+            os.unlink(junit_path)
+        except OSError:
+            pass
+
+    result["announced"] = _min_maturity(claim, result["tests_maturity"])
+    # PASS if the tests at least met the owner's claim; otherwise downgraded.
+    if MATURITY[result["tests_maturity"]] < MATURITY[claim]:
+        result["verdict"] = "downgraded"
+    return result
+
+
+def _parse_junit(path: str) -> dict:
+    """Aggregate counts from a JUnit XML file across all <testsuite> nodes."""
+    tests = failures = errors = skipped = 0
+    try:
+        root = ET.parse(path).getroot()
+    except (ET.ParseError, FileNotFoundError):
+        return {"n_selected": 0, "n_passed": 0, "n_failed": 0, "n_skipped": 0}
+    suites = root.iter("testsuite") if root.tag != "testsuite" else [root]
+    for s in suites:
+        tests += int(s.get("tests", 0))
+        failures += int(s.get("failures", 0))
+        errors += int(s.get("errors", 0))
+        skipped += int(s.get("skipped", 0))
+    bad = failures + errors
+    return {
+        "n_selected": tests,
+        "n_passed": tests - bad - skipped,
+        "n_failed": bad,
+        "n_skipped": skipped,
+    }
+
+
+def run_gate(manifest_path: str, cli_levels: str | None) -> list[dict]:
+    features = load_manifest(manifest_path)
+    return [_run_feature(f, cli_levels) for f in features]
+
+
+# ---------------------------------------------------------------------------
+# Output renderers
+# ---------------------------------------------------------------------------
+
+ICON = {"ok": "✓", "downgraded": "↓"}  # check / down-arrow
+
+
+def cmd_report(results: list[dict]) -> int:
+    title_w = max([len(r["title"]) for r in results] + [5])
+    tests_w = 20
+    print()
+    print(f"  {'FEATURE':<{title_w}}  {'CLAIM':<12}  {'ACHIEVED':<12}  {'TESTS':<{tests_w}}  VERDICT")
+    print(f"  {'-' * title_w}  {'-' * 12}  {'-' * 12}  {'-' * tests_w}  {'-' * 10}")
+    for r in results:
+        tests = f"{r['n_passed']}/{max(r['n_selected'] - r['n_skipped'], 0)} pass"
+        if r["n_skipped"]:
+            tests += f" ({r['n_skipped']} skip)"
+        verdict = "ok" if r["verdict"] == "ok" else "DOWNGRADED"
+        mark = ICON.get(r["verdict"], "?")
+        print(f"  {r['title']:<{title_w}}  {r['claim']:<12}  "
+              f"{r['announced']:<12}  {tests:<{tests_w}}  {mark} {verdict}")
+        if r["note"]:
+            print(f"  {' ' * title_w}  -> {r['note']}")
+    print()
+    downgrades = [r for r in results if r["verdict"] == "downgraded"]
+    if downgrades:
+        keys = ", ".join(r["key"] for r in downgrades)
+        print(f"  Note: {len(downgrades)} feature(s) downgraded below their claim: {keys}")
+        print("  Their code still ships; the release notes simply will not announce")
+        print("  them as supported. This does not block the merge.")
+        print()
+    return 0
+
+
+def cmd_run(results: list[dict]) -> int:
+    json.dump({"features": results}, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+def cmd_render_notes(results: list[dict], version: str) -> int:
+    supported = [r for r in results if r["announced"] == "supported"]
+    preview = [r for r in results if r["announced"] != "supported"]
+
+    out = [f"# Underworld3 {version}", ""]
+    out += [
+        "<!-- The Supported / Preview sections below are generated by",
+        "     scripts/release_gate.py from docs/release-notes/feature-manifest.yaml.",
+        "     Edit the Highlights and Contributors by hand. -->",
+        "",
+        "## Highlights",
+        "",
+        "- ",
+        "",
+        "## Supported (validated)",
+        "",
+        "<!-- Features whose tier_a/b validation passed on this release. Guaranteed. -->",
+        "",
+    ]
+    if supported:
+        for r in supported:
+            line = f"- **{r['title']}**"
+            if r["summary"]:
+                line += f" — {r['summary']}"
+            out.append(line)
+    else:
+        out.append("- _(none validated for this release)_")
+    out += [
+        "",
+        "## Preview (present, unguaranteed)",
+        "",
+        "<!-- Code is on main but NOT guaranteed to work. Use at your own risk. -->",
+        "",
+    ]
+    if preview:
+        for r in preview:
+            tag = "" if r["announced"] == "preview" else f" _({r['announced']})_"
+            line = f"- **{r['title']}**{tag}"
+            if r["summary"]:
+                line += f" — {r['summary']}"
+            out.append(line)
+    else:
+        out.append("- _(none)_")
+    out += [
+        "",
+        "## Bug Fixes",
+        "",
+        "- ",
+        "",
+        "## Contributors",
+        "",
+        "Thanks to everyone who contributed to this release.",
+        "",
+    ]
+    print("\n".join(out))
+    return 0
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(description="Underworld3 release validation gate")
+    p.add_argument("--manifest", default=DEFAULT_MANIFEST,
+                   help="path to feature-manifest.yaml")
+    p.add_argument("--levels", default=None,
+                   help="default level filter (e.g. '1,2'); per-feature levels override")
+    p.add_argument("--results", default=None,
+                   help="render-notes: read results JSON instead of re-running the gate")
+    sub = p.add_subparsers(dest="command", required=True)
+    sub.add_parser("report", help="run the gate and print a table")
+    sub.add_parser("run", help="run the gate and emit JSON")
+    rn = sub.add_parser("render-notes", help="emit Supported/Preview release-notes body")
+    rn.add_argument("version", help="release version, e.g. v3.1.0")
+
+    args = p.parse_args(argv)
+
+    # --results lets report/render-notes reuse a prior run's JSON instead of
+    # re-running the (slow) test selection. `run` always executes.
+    if args.results and args.command != "run":
+        with open(args.results) as fh:
+            results = json.load(fh).get("features", [])
+    else:
+        results = run_gate(args.manifest, args.levels)
+
+    if args.command == "report":
+        return cmd_report(results)
+    if args.command == "run":
+        return cmd_run(results)
+    if args.command == "render-notes":
+        return cmd_render_notes(results, args.version)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/uw b/uw
index 02b34835..cf61d764 100755
--- a/uw
+++ b/uw
@@ -927,6 +927,7 @@ run_setup() {
 
 # Show comprehensive help
 show_help() {
+    local verbose="${1:-0}"
     cat << 'EOF'
 UNDERWORLD3 ENVIRONMENT WRAPPER
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -1000,8 +1001,6 @@ COMMANDS
   Development:
     shell               Interactive pixi shell in the configured env (avoid bare 'pixi shell')
     jupyter [args]      Run jupyter (add --worktree NAME to open a worktree)
-    format              Run black
-    type-check          Run mypy
 
   Worktrees:
     worktree create <name> [prefix]   Create worktree (own .pixi, shared PETSc)
@@ -1016,6 +1015,29 @@ COMMANDS
     doctor              Check for configuration issues (PETSc mismatch, etc.)
     status              Check for updates on GitHub (without pulling)
     update              Pull latest changes and rebuild
+EOF
+    if [ "$verbose" = "1" ]; then
+        cat << 'EOF'
+
+  Developer / maintenance  (./uw dev <tool>):
+    dev release [opts]       Orchestrate development -> main promotion
+                             (--version vX.Y.Z  --rc N  --yes  --dry-run)
+    dev release-check [lvl]  Per-feature validation gate (dry-run; default 1,2)
+    dev branch-hygiene       Report/prune branches merged to development
+    dev feature-audit        List feature merges available to release
+    dev format               Run black
+    dev type-check           Run mypy
+
+    See docs/developer/guides/release-process.md  (or ./uw dev --help)
+EOF
+    else
+        cat << 'EOF'
+
+  Developer tools live under ./uw dev — reveal them with:
+    ./uw --help all          (shown by default on *-dev environments)
+EOF
+    fi
+    cat << 'EOF'
 
   Any command not listed is passed to: pixi run -e $ENV <command>
 
@@ -1028,6 +1050,42 @@ FILES
 EOF
 }
 
+show_dev_help() {
+    cat << 'EOF'
+UNDERWORLD3 DEVELOPER TOOLS  —  ./uw dev <command>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Maintainer and contributor tooling. These run in any environment, but the
+runtime/default envs are deliberately stripped down for beginners, demos and
+binder — so on those envs ./uw --help hides this section (reveal it with
+./uw --help all). On a *-dev environment it is shown by default.
+
+  Releasing (development -> main):
+    dev release [opts]       Orchestrate the quarterly promotion: tag an RC on
+                             development, run full validation + the per-feature
+                             gate, scaffold release notes, open the dev->main PR.
+                             Stops before the production tag (review gate intact).
+                             Options: --version vX.Y.Z  --rc N  --yes  --dry-run
+    dev release-check [lvl]  Per-feature validation gate, dry-run (default 1,2).
+                             Tells you which features pass — i.e. are announceable
+                             as "supported". Run on development.
+    dev branch-hygiene       Report branches merged into development, branches
+                             with open PRs, and stale branches. Add --prune to
+                             delete merged branches (confirms each).
+    dev feature-audit        List feature-branch PR merges into development since
+                             the last release — the pool of features available to
+                             announce. Map these to entries in the manifest.
+                             [--all also lists bugfix/docs; --since <ref> overrides]
+
+  Code quality:
+    dev format               Run black over src/ and tests/
+    dev type-check           Run mypy over src/
+
+  Guide: docs/developer/guides/release-process.md
+
+EOF
+}
+
 # Check for updates on remote (without pulling)
 check_for_updates() {
     local quiet="${1:-false}"
@@ -1451,6 +1509,330 @@ worktree_remove() {
     echo -e "${GREEN}✓${NC} Worktree '$name' removed"
 }
 
+# ── Release tooling ─────────────────────────────────────────────────────────
+# Maturity-gated quarterly promotion of development -> main.
+# See docs/developer/guides/release-process.md
+
+# Small y/N confirm helper. Returns 0 on yes. Honours an assume-yes flag.
+_confirm() {
+    local prompt="$1" assume_yes="${2:-0}"
+    [ "$assume_yes" -eq 1 ] && return 0
+    read -p "$prompt [y/N]: " _c
+    [ "$_c" = "y" ] || [ "$_c" = "Y" ]
+}
+
+# ./uw dev release-check [levels]
+# Dry-run of the per-feature validation gate against the current checkout.
+# Read-only; tells you which features currently pass (announceable as supported).
+run_release_check() {
+    local levels="${1:-1,2}"
+    cd "$SCRIPT_DIR"
+    local branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+    echo -e "${BOLD}Release validation gate${NC}  (branch: $branch, levels: $levels)"
+    if [ "$branch" != "development" ]; then
+        echo -e "  ${YELLOW}note:${NC} normally run on 'development'; you are on '$branch'."
+    fi
+    $PIXI run -e "$(get_env)" python "$SCRIPT_DIR/scripts/release_gate.py" \
+        --levels "$levels" report
+}
+
+# ./uw dev branch-hygiene [--prune]
+# Report (and optionally delete) branches that are merged into development.
+# Never touches branches with an open PR. Targets the "dangling branches" pileup.
+run_branch_hygiene() {
+    local do_prune=0
+    [ "$1" = "--prune" ] && do_prune=1
+    cd "$SCRIPT_DIR"
+
+    if [ ! -d "$SCRIPT_DIR/.git" ]; then
+        echo "Not a git repository"; exit 1
+    fi
+
+    echo -e "${BOLD}Fetching and pruning remote-tracking refs...${NC}"
+    git fetch --prune --quiet origin 2>/dev/null || git fetch --prune origin
+
+    # Head branches of open PRs — never prune these.
+    # gh_ok is set only when the open-PR query genuinely succeeds. An empty list
+    # from a *successful* query means "no open PRs" (safe). An empty list from a
+    # failed/unauth'd query must NOT be treated as "no open PRs" — otherwise
+    # --prune could delete branches that actually have open PRs.
+    local open_pr_branches="" gh_ok=0
+    if command -v gh >/dev/null 2>&1; then
+        if open_pr_branches=$(gh pr list --state open --limit 200 \
+            --json headRefName --jq '.[].headRefName' 2>/dev/null); then
+            gh_ok=1
+        else
+            echo -e "  ${YELLOW}gh could not list open PRs (auth/access?) — pruning disabled.${NC}"
+        fi
+    else
+        echo -e "  ${YELLOW}gh not found — cannot cross-check open PRs; pruning disabled.${NC}"
+    fi
+
+    # Remote branches merged into development (prune candidates), minus the trunks.
+    local merged
+    merged=$(git branch -r --merged origin/development 2>/dev/null \
+        | sed 's/^[* ]*//' \
+        | grep '^origin/' \
+        | grep -vE 'origin/(HEAD|development|main)$' \
+        | sed 's#^origin/##' \
+        | sort -u)
+
+    echo ""
+    echo -e "${BOLD}Merged into development (safe to delete):${NC}"
+    local prunable=()
+    if [ -z "$merged" ]; then
+        echo "  (none)"
+    else
+        while IFS= read -r b; do
+            [ -z "$b" ] && continue
+            if echo "$open_pr_branches" | grep -qx "$b"; then
+                echo -e "  ${YELLOW}$b${NC}  (has open PR — keeping)"
+            else
+                echo -e "  ${GREEN}$b${NC}"
+                prunable+=("$b")
+            fi
+        done <<< "$merged"
+    fi
+
+    echo ""
+    echo -e "${BOLD}Open PRs (do NOT prune):${NC}"
+    if [ -z "$open_pr_branches" ]; then
+        echo "  (none)"
+    else
+        echo "$open_pr_branches" | sed 's/^/  /'
+    fi
+
+    # Stale: not merged, no open PR, last commit older than 90 days.
+    echo ""
+    echo -e "${BOLD}Stale branches (unmerged, no open PR, >90 days):${NC}"
+    local now=$(date +%s)
+    local cutoff=$(( 90 * 24 * 3600 ))
+    local found_stale=0
+    while IFS='|' read -r b ts; do
+        [ -z "$b" ] && continue
+        b=${b#origin/}
+        case "$b" in HEAD|development|main) continue ;; esac
+        echo "$merged" | grep -qx "$b" && continue
+        echo "$open_pr_branches" | grep -qx "$b" && continue
+        local age=$(( now - ts ))
+        if [ "$age" -gt "$cutoff" ]; then
+            echo -e "  ${YELLOW}$b${NC}  ($(( age / 86400 ))d)"
+            found_stale=1
+        fi
+    done <<< "$(git for-each-ref --format='%(refname:short)|%(committerdate:unix)' refs/remotes/origin)"
+    [ "$found_stale" -eq 0 ] && echo "  (none)"
+
+    echo ""
+    if [ "$do_prune" -eq 0 ]; then
+        echo "Report only. Re-run with --prune to delete merged branches:"
+        echo "  ./uw dev branch-hygiene --prune"
+        return
+    fi
+
+    if [ "$gh_ok" -eq 0 ]; then
+        echo -e "${YELLOW}Refusing to --prune: the open-PR cross-check is unavailable,${NC}"
+        echo "so a branch with an open PR could be deleted by mistake."
+        echo "Authenticate gh ('gh auth login') and retry."
+        return
+    fi
+
+    if [ "${#prunable[@]}" -eq 0 ]; then
+        echo "Nothing to prune."
+        return
+    fi
+
+    echo -e "${BOLD}Prune merged branches:${NC}"
+    local b
+    for b in "${prunable[@]}"; do
+        read -p "  Delete origin/$b (and local if present)? [y/N]: " confirm
+        if [ "$confirm" = "y" ] || [ "$confirm" = "Y" ]; then
+            git push origin --delete "$b" 2>/dev/null \
+                && echo -e "    ${GREEN}✓${NC} deleted origin/$b" \
+                || echo -e "    ${YELLOW}!${NC} could not delete origin/$b"
+            git branch -D "$b" 2>/dev/null \
+                && echo -e "    ${GREEN}✓${NC} deleted local $b" || true
+        fi
+    done
+}
+
+# ./uw dev feature-audit [--all] [--since <ref>]
+# List feature-branch PR merges into development since the last release, so you
+# know what is available to announce. Candidates for the release manifest.
+run_feature_audit() {
+    local show_all=0 since=""
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --all)   show_all=1; shift ;;
+            --since) since="$2"; shift 2 ;;
+            *) echo "Usage: ./uw dev feature-audit [--all] [--since <ref>]"; exit 1 ;;
+        esac
+    done
+    cd "$SCRIPT_DIR"
+    git fetch --tags --quiet origin 2>/dev/null
+
+    # Baseline: explicit --since, else the last release tag if it is on
+    # development, else the point where development last diverged from main.
+    local base base_label
+    if [ -n "$since" ]; then
+        base="$since"; base_label="$since"
+    else
+        local last_tag=$(git tag --list 'v*' --sort=-v:refname | head -1)
+        if [ -n "$last_tag" ] && git merge-base --is-ancestor "$last_tag" origin/development 2>/dev/null; then
+            base="$last_tag"; base_label="release $last_tag"
+        else
+            base=$(git merge-base origin/main origin/development)
+            base_label="$(git rev-parse --short "$base") (main divergence point)"
+        fi
+    fi
+    local base_date=$(git log -1 --format=%cd --date=short "$base" 2>/dev/null)
+
+    echo -e "${BOLD}Feature merges into development since ${base_label}, ${base_date}:${NC}"
+    echo "  candidates for docs/release-notes/feature-manifest.yaml"
+    echo ""
+
+    local pattern='from [^ ]*/feature/'
+    [ "$show_all" -eq 1 ] && pattern='from [^ ]*/(feature|bugfix|docs)/'
+
+    local count=0
+    while IFS='|' read -r d s; do
+        [ -z "$s" ] && continue
+        local pr=$(echo "$s" | grep -oE '#[0-9]+' | head -1)
+        local br=$(echo "$s" | sed -E 's#.*from [^/ ]+/##')
+        printf "  ${GREEN}%-12s${NC} %-7s %s\n" "$d" "$pr" "$br"
+        count=$((count + 1))
+    done <<< "$(git log "$base"..origin/development --merges --first-parent \
+        --date=short --format='%cd|%s' 2>/dev/null | grep -E "$pattern")"
+
+    local listed=$(grep -c '^  - key:' docs/release-notes/feature-manifest.yaml 2>/dev/null || echo 0)
+    echo ""
+    echo "  $count merge(s) found. Manifest currently lists $listed feature(s)."
+    echo "  Note: only PR-merge commits are detected; squash-merged PRs won't appear."
+    echo "  Validated-test coverage:  python scripts/check_manifest_coverage.py"
+}
+
+# ./uw dev release [--version vX.Y.Z] [--rc N] [--yes] [--dry-run]
+# Orchestrate the quarterly development -> main promotion. Every state-changing
+# step is confirmed. Stops BEFORE the production tag push so main's branch
+# protection (PR + review) stays intact; CI release.yml owns the GitHub release.
+run_release() {
+    local version="" rc="1" assume_yes=0 dry_run=0
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --version) version="$2"; shift 2 ;;
+            --rc) rc="$2"; shift 2 ;;
+            --yes|-y) assume_yes=1; shift ;;
+            --dry-run) dry_run=1; shift ;;
+            *) echo "Unknown option: $1"; echo "Usage: ./uw dev release [--version vX.Y.Z] [--rc N] [--yes] [--dry-run]"; exit 1 ;;
+        esac
+    done
+
+    cd "$SCRIPT_DIR"
+
+    echo -e "${BOLD}[1/7] Preflight${NC}"
+    local branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
+    if [ "$branch" != "development" ]; then
+        echo -e "  ${YELLOW}Release must be cut from 'development' in the main checkout (you are on '$branch').${NC}"
+        exit 1
+    fi
+    if [ -n "$(git status --porcelain)" ]; then
+        echo -e "  ${YELLOW}Working tree is not clean. Commit or stash first.${NC}"
+        exit 1
+    fi
+    git fetch --quiet origin 2>/dev/null || git fetch origin
+    local behind=$(git rev-list --count HEAD..origin/development 2>/dev/null || echo 0)
+    if [ "$behind" -gt 0 ]; then
+        echo -e "  ${YELLOW}Local development is $behind commit(s) behind origin. Pull first.${NC}"; exit 1
+    fi
+    local unpushed=$(git rev-list --count origin/development..HEAD 2>/dev/null || echo 0)
+    if [ "$unpushed" -gt 0 ]; then
+        echo -e "  ${YELLOW}Local development has $unpushed unpushed commit(s). Push first so the RC tag matches what reviewers and CI see on origin.${NC}"; exit 1
+    fi
+    local ahead=$(git rev-list --count origin/main..origin/development 2>/dev/null || echo 0)
+    echo -e "  ${GREEN}✓${NC} on development, clean, in sync with origin, $ahead commit(s) ahead of main"
+
+    echo ""
+    echo -e "${BOLD}[2/7] Version${NC}"
+    if [ -z "$version" ]; then
+        local last_tag=$(git tag --list 'v*' --sort=-v:refname | head -1)
+        echo "  Last release tag: ${last_tag:-none}"
+        read -p "  Release version (e.g. v3.1.0): " version
+    fi
+    [ -z "$version" ] && { echo "No version given."; exit 1; }
+    case "$version" in v*) ;; *) version="v$version" ;; esac
+    local rc_tag="${version}rc${rc}"
+    echo "  Release:  $version"
+    echo "  RC tag:   $rc_tag  (pushed to development now; production tag is manual after merge)"
+
+    echo ""
+    echo -e "${BOLD}[3/7] Tag release candidate on development${NC}"
+    if [ "$dry_run" -eq 1 ]; then
+        echo "  (dry-run) would: git tag $rc_tag && git push origin $rc_tag"
+    elif _confirm "  Tag and push $rc_tag on development?" "$assume_yes"; then
+        git tag "$rc_tag" && git push origin "$rc_tag" \
+            && echo -e "  ${GREEN}✓${NC} pushed $rc_tag (CI builds a prerelease)"
+    else
+        echo "  Skipped RC tag."
+    fi
+
+    echo ""
+    echo -e "${BOLD}[4/7] Full validation + per-feature gate${NC}"
+    local results_json="${TMPDIR:-/tmp}/uw_release_gate_${version}.json"
+    if [ "$dry_run" -eq 1 ]; then
+        echo "  (dry-run) would run: ./scripts/test_levels.sh 1,2,3 --isolation"
+        echo "  (dry-run) would run: release_gate.py --levels 1,2,3 run > $results_json"
+    else
+        echo "  Running full test suite (levels 1,2,3, isolated)..."
+        $PIXI run -e "$(get_env)" ./scripts/test_levels.sh 1,2,3 --isolation || \
+            echo -e "  ${YELLOW}! Test suite reported failures — review before publishing.${NC}"
+        echo "  Running per-feature maturity gate..."
+        $PIXI run -e "$(get_env)" python "$SCRIPT_DIR/scripts/release_gate.py" \
+            --levels 1,2,3 run > "$results_json"
+        $PIXI run -e "$(get_env)" python "$SCRIPT_DIR/scripts/release_gate.py" \
+            --results "$results_json" report
+    fi
+
+    echo ""
+    echo -e "${BOLD}[5/7] Release notes${NC}"
+    local notes_file="docs/release-notes/${version}.md"
+    if [ "$dry_run" -eq 1 ]; then
+        echo "  (dry-run) would render notes to $notes_file"
+    elif [ -f "$notes_file" ]; then
+        echo -e "  ${YELLOW}$notes_file already exists — not overwriting.${NC}"
+    elif _confirm "  Generate $notes_file from the gate results?" "$assume_yes"; then
+        $PIXI run -e "$(get_env)" python "$SCRIPT_DIR/scripts/release_gate.py" \
+            --results "$results_json" render-notes "$version" > "$notes_file"
+        echo -e "  ${GREEN}✓${NC} wrote $notes_file — edit Highlights & Contributors, then commit it."
+    fi
+
+    echo ""
+    echo -e "${BOLD}[6/7] Open development -> main PR${NC}"
+    if [ "$dry_run" -eq 1 ]; then
+        echo "  (dry-run) would: gh pr create --base main --head development ..."
+    elif ! command -v gh >/dev/null 2>&1; then
+        echo -e "  ${YELLOW}gh not found — open the development->main PR manually.${NC}"
+    elif _confirm "  Create the development -> main PR now?" "$assume_yes"; then
+        if [ -f "$notes_file" ]; then
+            gh pr create --base main --head development \
+                --title "Release $version" --body-file "$notes_file" \
+                && echo -e "  ${GREEN}✓${NC} PR opened"
+        else
+            gh pr create --base main --head development \
+                --title "Release $version" --body "Release $version" \
+                && echo -e "  ${GREEN}✓${NC} PR opened"
+        fi
+    fi
+
+    echo ""
+    echo -e "${BOLD}[7/7] Final tag (manual, after the PR merges to main)${NC}"
+    echo "  Once the development -> main PR is reviewed and merged:"
+    echo "    git checkout main && git pull"
+    echo "    git tag $version && git push origin $version"
+    echo "  CI (release.yml) then publishes the GitHub Release from $notes_file."
+    echo ""
+    echo -e "${GREEN}Done.${NC} The production tag is deliberately left for you to push"
+    echo "after the merge, so main's PR + review gate stays intact."
+}
+
 # Check if an environment is installed
 env_installed() {
     [ -d "$SCRIPT_DIR/.pixi/envs/$1" ]
@@ -1713,8 +2095,47 @@ case "${1:-}" in
                 ;;
         esac
         ;;
+    dev)
+        shift
+        cmd="${1:-help}"
+        case "$cmd" in
+            help|--help|-h|"")
+                show_dev_help
+                ;;
+            *)
+                # Soft note, not a block: dev tools run in any environment, but
+                # runtime/default are the stripped-down beginner/binder/teaching
+                # envs, so flag when a developer tool is used there.
+                case "$(get_env)" in
+                    *dev*) ;;
+                    *) echo -e "${YELLOW}note:${NC} 'dev $cmd' is a developer tool; you're on '$(get_env)' (a user env). Running anyway." >&2 ;;
+                esac
+                shift
+                case "$cmd" in
+                    release)        run_release "$@" ;;
+                    release-check)  run_release_check "$@" ;;
+                    branch-hygiene) run_branch_hygiene "$@" ;;
+                    feature-audit)  run_feature_audit "$@" ;;
+                    format)         exec $PIXI run -e "$(get_env)" format "$@" ;;
+                    type-check)     exec $PIXI run -e "$(get_env)" type-check "$@" ;;
+                    *)
+                        echo "Unknown dev command: $cmd"
+                        echo ""
+                        show_dev_help
+                        exit 1
+                        ;;
+                esac
+                ;;
+        esac
+        ;;
     --help|-h|help)
-        show_help
+        shift
+        _help_verbose=0
+        case "$(get_env)" in *dev*) _help_verbose=1 ;; esac
+        for _a in "$@"; do
+            case "$_a" in all|--verbose|-v) _help_verbose=1 ;; esac
+        done
+        show_help "$_help_verbose"
         ;;
     *)
         exec $PIXI run -e "$(get_env)" "$@"