# graceful-handoff (v3.0)

É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`. |
| `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` → skriv/overskriv STATE.md i fast format
→ `--commit` → push (Forgejo) → fast avslutningslinje.

## STATE.md-format (ufravikelig)

`# STATE — <navn>` + undertittel → **`## 👉 NESTE — START HER`** ØVERST (hvor vi er + nummererte
neste steg + pekere til hva som må leses) → faste seksjoner (oppdrag/kjøremodus, gotchas,
push-status, repo/env) + kort historikk UNDER. Maks ~60 linjer. Overskriv, ikke append.

## 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'
```

30 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`.

## 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).

## Release (polyrepo — egen gated handling)

En versjonsbump er ikke fullført før: (1) `v3.0.0`-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.