Kjell Tore Guttormsen
be0a463e02
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
109 lines
6.6 KiB
Markdown
109 lines
6.6 KiB
Markdown
# graceful-handoff (v3.2)
|
|
|
|
Én-kommandos sesjonsoverlevering inn i **STATE.md-kontinuitetssystemet**. `/graceful-handoff`
|
|
når et naturlig stoppunkt, overskriver nærmeste `STATE.md` med en komplett state-of-play
|
|
(obligatorisk «👉 NESTE — START HER»-blokk øverst), og committer per remote-policy. Skill-only
|
|
arkitektur (`disable-model-invocation: true`) + ett slankt deterministisk hjelpeskript. **Ingen hooks.**
|
|
|
|
## Hva den gjør
|
|
|
|
`/graceful-handoff` er operasjonaliseringen av den globale «Session Slutt»-rituelen, sentrert
|
|
på STATE.md (ett av tre kontinuitets-lag: `STATE.md` + auto-memory `MEMORY.md` + `CLAUDE.md`).
|
|
Den skriver IKKE lenger en egen `NEXT-SESSION`-artefakt — det var nettopp den typen lokale
|
|
handover-påfunn regimet forbyr. STATE.md ER overleveringen.
|
|
|
|
- **Manuelt, når du vil:** `/graceful-handoff`. Sesjonen avslutter ved første naturlige punkt og
|
|
etterlater en selvtilstrekkelig STATE.md.
|
|
- **Ny sesjon:** den globale `~/.claude/hooks/session-start.sh` injiserer nærmeste STATE.md
|
|
automatisk. Pluginen trenger ingen egen auto-load.
|
|
|
|
## Arkitektur — modellen skriver, skriptet assisterer
|
|
|
|
Bare sesjonsmodellen har konteksten til å fylle «👉 NESTE»-blokken meningsfullt. Et deterministisk
|
|
`git log`-snapshot kan det aldri. Derfor er ansvaret invertert mot v2:
|
|
|
|
| Fil | Rolle |
|
|
|-----|-------|
|
|
| `skills/graceful-handoff/SKILL.md` | Rituelet, modell-drevet (full kontekst). Frontmatter: `disable-model-invocation: true`, **ingen `model:`-pin** (arver sesjonsmodell — STATE.md er human-facing syntese → Opus-kvalitet), sub-scoped `allowed-tools` inkl. `Write` og `Skill` (sistnevnte for `repo-mailbox:route`). |
|
|
| `scripts/handoff-pipeline.mjs` | Slank deterministisk STATE-hjelper. `--plan` (resolver nærmeste STATE.md + klassifiser remote + git-fakta, read-only), `--commit` (stager KUN STATE.md når tracked + eksplisitte `--also`-stier; aldri `git add -A`), `--dry-run`. Returnerer JSON. Testbar uten LLM. |
|
|
|
|
Rituelet (SKILL.md): nå naturlig stoppunkt → `--plan` → rut neste økt (`repo-mailbox:route`) →
|
|
skriv/overskriv STATE.md i fast format → `--commit` → push (Forgejo) → fast avslutningslinje.
|
|
|
|
## STATE.md-format (ufravikelig) — ÉN kopi, og den bor i SKILL.md
|
|
|
|
Formatet sto tidligere gjengitt her. Det er **fjernet med vilje**: to kopier av samme mal drifter
|
|
fra hverandre, og en mal i en prosa-fil kan ikke testes. **Ikke gjenopprett den her.**
|
|
|
|
Autoriteten er `skills/graceful-handoff/SKILL.md` steg 4 («Skriv/overskriv STATE.md — UFRAVIKELIG
|
|
FORMAT»), som er der rituelet faktisk leses fra ved kjøring, og som `tests/skill-structure.test.mjs`
|
|
låser. Endres formatet (globalt CLAUDE.md er kilden), endres SKILL.md — og testen fanger drift.
|
|
|
|
Det ene som hører hjemme her, fordi det er en avhengighet og ikke en mal: `repo-mailbox` er en
|
|
**myk** avhengighet. Steg 3 invokerer `repo-mailbox:route` for board-/route-linjene og for
|
|
avslutningslinjens modellfelt; er den ikke installert, faller rituelet tilbake til et uttalt
|
|
skjønnsvalg og fortsetter.
|
|
|
|
## Remote-policy (STATE må aldri nå et offentlig speil)
|
|
|
|
Hjelperen klassifiserer `origin`:
|
|
- `github.com` eller `open/`-Forgejo-namespace → **public** → STATE.md local-only (gitignored), committes aldri.
|
|
- ellers (privat Forgejo `ktg/…`) → **private** → STATE.md tracked + committet.
|
|
|
|
Den autoritative commit-beslutningen er `git check-ignore STATE.md`; `remote_class` driver kun et
|
|
`leak_warning` når de to er inkonsistente (offentlig remote, men STATE.md ikke gitignored).
|
|
|
|
**Denne repoen har `open/`-remote → STATE.md er gitignored (local-only).** Plugin-koden er offentlig;
|
|
state-of-play er det ikke.
|
|
|
|
## Eksplisitt staging (ufravikelig)
|
|
|
|
`--commit` stager KUN STATE.md (+ eksplisitte `--also`-stier). ALDRI `git add -A` — det scoopper opp
|
|
ubeslektet WIP. Regresjonstest håndhever dette. Pre-commit hooks respekteres uten `--no-verify`.
|
|
|
|
## Tester
|
|
|
|
```bash
|
|
node --test 'tests/**/*.test.mjs'
|
|
```
|
|
|
|
42 tester på tvers av 3 filer (`skill-structure`, `scripts/handoff-pipeline`, `plugin-manifest`).
|
|
Pipelinen er deterministisk og testes uten LLM-kall: `--plan`/`--commit`-JSON, nærmeste-STATE-resolusjon,
|
|
remote-klassifisering, staging-disiplin (no-`git add -A`-regresjon), gitignored-STATE-skip, detached-HEAD,
|
|
`--dry-run`.
|
|
|
|
**Vær ærlig om hva de beviser.** Ritual-testene i `skill-structure` er prosa-grep — de er
|
|
drift-vakter, ikke korrekthetsbevis. Ingen av dem kjører rituelet. Den faktiske verifiseringen er
|
|
en manuell `/graceful-handoff` mot et scratch-repo; grønne tester er ikke det samme som et
|
|
verifisert ritual.
|
|
|
|
## Versjonering
|
|
|
|
- v1.0.0 (2026-04-19): deklarativ command, NEXT-SESSION-artefakt
|
|
- v2.0.0 (2026-05-01): skill-arkitektur + JSON-pipeline + 3 hooks + auto-trigger (BREAKING)
|
|
- v2.1.0 (2026-05-01): modell-bevisst kontekstvindu (4-stegs resolution-kjede)
|
|
- v3.0.0 (2026-06-23): **STATE.md-integrasjon (BREAKING).** Fjernet NEXT-SESSION-artefakt + alle 3 hooks; invertert pipeline (modellen skriver STATE.md, skriptet assisterer); remote-aware tracked/local-only-policy; fjernet Sonnet-pin.
|
|
- v3.1.0 (2026-06-24): fjernet hardkodet push-vindu — push er nå ubetinget (kun Forgejo, fortsatt user-triggered).
|
|
- v3.2.0 (2026-08-09): ritualet synket med global «Session Slutt» — nytt route-steg (`repo-mailbox:route`) før STATE-skrivingen, board-/route-/route-last-linjer i malen, avslutningslinjen utvidet fra 3 til 6 felt (Innboks, Modell neste økt, Oppstartskommando), STATE-formatet konsolidert til én kopi (SKILL.md).
|
|
|
|
## 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. 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.
|