docs(graceful-handoff): correct the release command — it was silently wrong

The documented form `release-plugin.mjs graceful-handoff <versjon>` drops the
version argument on the floor. parseArgs only accepts a version via
`--version X.Y.Z`; a bare positional is discarded because `name` is already
set and the token does not start with `--`. It appeared to work solely
because plugin.json happened to carry the intended version. The first time
those disagree, the wrong version ships.

The documented form was also missing `--create-tag --write --commit --push`.
Without them the script is a dry-run, and without `--create-tag` it exits
BLOCKED when the tag does not exist yet — which is every first release.

Also replaces the "check-versions.mjs grønn / 0 ERROR" criterion. That gate is
unreachable: the run exit-codes 1 on a pre-existing repo-mailbox ERROR owned
by another repo. The honest criterion is that the graceful-handoff row reads
✓ OK.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017kWX5Si98v64DQ7MWHzt8P
This commit is contained in:
Kjell Tore Guttormsen 2026-08-09 21:31:02 +02:00
commit be0a463e02

View file

@ -89,5 +89,21 @@ verifisert ritual.
## Release (polyrepo — egen gated handling)
En versjonsbump er ikke fullført før: (1) `vX.Y.Z`-tag laget + pushet i denne repoen, OG (2)
katalogens `ref` bumpet til samme tag med `check-versions.mjs` grønn. Bruk
`../catalog/scripts/release-plugin.mjs graceful-handoff <versjon>` (atomisk). Krever operatør-go.
katalogens `ref` bumpet til samme tag. Krever operatør-go.
```bash
node ../catalog/scripts/release-plugin.mjs graceful-handoff --create-tag --write --commit --push
```
**Skriptet er dry-run uten flagg** — bar invokasjon printer bare planen. De fire flaggene gjør tag
+ katalog-ref atomisk i én kjøring; `--create-tag` er ikke valgfri når taggen ennå ikke finnes
(uten den stopper kjøringen med `BLOCKED`).
**Versjonen tas fra `plugin.json`, og overstyres KUN med `--version X.Y.Z`.** En bar posisjonell
versjon (`… graceful-handoff 3.2.0`) blir **stilltiende ignorert**`parseArgs` har allerede satt
`name`, og argumentet starter ikke med `--`, så det faller ut. Det ser ut til å virke så lenge
`plugin.json` tilfeldigvis er enig; første gang den ikke er det, slipper feil versjon gjennom.
**Verifisering:** `node ../catalog/scripts/check-versions.mjs` — kriteriet er at **raden for
`graceful-handoff` er `✓ OK`**, ikke at kjøringen er grønn. Skriptet exit-koder på hele katalogen,
så ERROR/WARN fra andre plugins (som er andre repos ansvar) holder den rød uansett hva vi gjør.