feat: state-machine release CLI with stable-base bumping

- Replace positional BUMP arg with --bump keyword option
- Replace --promote with --final (finalize RC or skip RC)
- Remove --rc flag (RC is default for --bump)
- Add 'release status' subcommand showing state and permitted commands
- --bump in RC mode abandons current RC, bumps from last stable tag
- Warning emitted when abandoning an active RC series
- 34 tests covering all state machine transitions

Author: Simon-McIntosh

AGENTS.md

@@ -617,30 +617,31 @@ query('''
 
 ### Release Workflow
 
-The release CLI uses semantic bumps (`major`/`minor`/`patch`) and pushes all graph variants automatically.
+The release CLI is state-machine driven. State is derived from the latest git tag:
 
-```bash
-# Release candidate (v4.0.0 → v5.0.0-rc1)
-uv run imas-codex release major --rc -m 'IMAS DD 4.1.0 support'
-
-# Increment RC (v5.0.0-rc1 → v5.0.0-rc2)
-uv run imas-codex release --rc -m 'Fix CI issues'
+- **Stable** (`vX.Y.Z`) — on a release
+- **RC mode** (`vX.Y.Z-rcN`) — testing a release candidate
 
-# Promote RC to release (v5.0.0-rc2 → v5.0.0)
-uv run imas-codex release --promote -m 'Production release'
+```bash
+# Check current state and permitted commands
+uv run imas-codex release status
 
-# Patch release (v5.0.0 → v5.0.1)
-uv run imas-codex release patch -m 'Bug fixes'
+# From stable (e.g., v5.0.0):
+uv run imas-codex release --bump major -m 'IMAS DD 4.1.0 support'    # → v6.0.0-rc1
+uv run imas-codex release --bump minor -m 'New discovery features'    # → v5.1.0-rc1
+uv run imas-codex release --bump patch -m 'Bug fixes'                 # → v5.0.1-rc1
+uv run imas-codex release --bump major --final -m 'Direct release'    # → v6.0.0 (skip RC)
 
-# Test on fork before upstream
-uv run imas-codex release minor --rc --remote origin -m 'Test'
+# From RC mode (e.g., v5.0.0-rc1):
+uv run imas-codex release -m 'Fix CI issues'                          # → v5.0.0-rc2 (increment)
+uv run imas-codex release --final -m 'Production release'             # → v5.0.0 (finalize)
+uv run imas-codex release --bump patch -m 'Abandon RC, new patch'     # → v5.0.1-rc1 (new RC)
 
-# Code-only release (no graph push)
-uv run imas-codex release patch --skip-graph -m 'Docs update'
+# Options: --remote, --skip-graph, --skip-git, --dry-run, --version
 ```
 
 The release command:
-1. Computes the next version from the latest git tag
+1. Computes the next version from the latest git tag (state machine)
 2. Validates no private fields in graph
 3. Tags DDVersion node with release metadata
 4. Pushes **all** graph variants to GHCR (imas-only + full + per-facility)

README.md

@@ -722,20 +722,17 @@ This creates `ghcr.io/iterorganization/imas-codex-graph-tcv` containing only TCV
 
 ### Releases
 
-The release CLI computes semantic versions from git tags and pushes all graph variants:
+The release CLI uses a state machine derived from the latest git tag — **stable** (`vX.Y.Z`) or **RC mode** (`vX.Y.Z-rcN`):
 
 ```bash
-# Release candidate (v4.0.0 → v5.0.0-rc1)
-imas-codex release major --rc -m 'IMAS DD 4.1.0 support'
-
-# Promote RC to release (v5.0.0-rc1 → v5.0.0)
-imas-codex release --promote -m 'Production release'
-
-# Patch release (v5.0.0 → v5.0.1)
-imas-codex release patch -m 'Bug fixes'
+imas-codex release status                                      # Show state + permitted commands
+imas-codex release --bump major -m 'IMAS DD 4.1.0 support'     # → v6.0.0-rc1 (from stable)
+imas-codex release -m 'Fix CI issues'                          # → v6.0.0-rc2 (increment RC)
+imas-codex release --final -m 'Production release'             # → v6.0.0 (finalize)
+imas-codex release --bump patch --final -m 'Hotfix'            # → v6.0.1 (direct release)
 ```
 
-Each release automatically pushes both `imas-codex-graph-imas` (DD-only) and `imas-codex-graph` (full) to GHCR, then creates a git tag that triggers CI to build Docker containers.
+Each release pushes all graph variants to GHCR, then creates a git tag that triggers CI.
 
 **Graph package variants:**
 
@@ -745,6 +742,8 @@ Each release automatically pushes both `imas-codex-graph-imas` (DD-only) and `im
 | `imas-codex-graph` | All facilities + DD | Private |
 | `imas-codex-graph-{facility}` | Single facility + DD | Private |
 
+**Setup:** Set `GHCR_TOKEN` with `write:packages` scope. Add upstream remote: `git remote add upstream https://github.com/iterorganization/imas-codex.git`
+
 ### Docker Compose
 
 ```bash