docs(graceful-handoff): 2.0 — sync README, CLAUDE.md, root README

plugins/graceful-handoff/CLAUDE.md

@@ -1,40 +1,63 @@
-# graceful-handoff
+# graceful-handoff (v2.0)
 
-Én kommando (`/graceful-handoff`) som produserer en komplett sesjonsoverlevering i ett steg: NEXT-SESSION-artefakt, commit+push, og copy-paste-prompt for neste sesjon.
+Auto-trigger sesjonsoverlevering ved kontekst-terskel, med manuell `/graceful-handoff` som backup. Skill-arkitektur (`disable-model-invocation: true`), deterministisk JSON-pipeline, og tre hooks som dekker hint, auto-eksekvering, og auto-load.
 
 ## Når brukes den
 
-Når du nærmer deg kontekst-trøskelen (typisk 60-70% på Opus 4.7) og må starte en ny sesjon. Kommandoen tar jobben med å oppsummere state og pushe ferdig arbeid fra minutter ned til sekunder.
+- **Automatisk:** Stop hook fyrer ved estimert ≥70% kontekst-bruk. Skriver artefakt + commit. Push gjenstår manuell.
+- **Manuelt:** `/graceful-handoff` ved 60-70% (eller når som helst). statusLine viser hint ved 60% og urgent ved 70%.
+- **Ny sesjon:** SessionStart hook auto-leser handoff-fil ved `source: resume` eller `source: compact` og injiserer i kontekst.
 
-## Hva den skriver
+## Komponenter
 
-| Fil | Når |
-|-----|-----|
-| `NEXT-SESSION-PROMPT.local.md` (eller `NEXT-SESSION-<slug>.local.md`) | Alltid — hovedartefakt med 7 seksjoner (Hvorfor / Status / Fortsett / Push-policy / Verifisering / Husk) |
-| `REMEMBER.md` | Hvis den finnes — oppdaterer "Sist oppdatert" og PÅGÅENDE-seksjon |
-| `TODO.md` | Hvis den finnes — flytter ferdige items, legger til neste-økt-items |
-| Commit + push | Hvis ucommittede endringer finnes OG `--no-commit` ikke er gitt |
+| Fil | Rolle |
+|-----|-------|
+| `skills/graceful-handoff/SKILL.md` | Slash-command-handler. Frontmatter: `disable-model-invocation: true`, `model: claude-sonnet-4-6`, sub-scoped `allowed-tools`. Body orkestrerer pipeline-skriptet. |
+| `scripts/handoff-pipeline.mjs` | Deterministisk Node-skript. Klassifiserer handoff-type, skriver artefakt, håndterer commit-bekreftelse, returnerer JSON. |
+| `hooks/scripts/statusline-monitor.mjs` | Display-only hint. Leser `context_window.used_percentage` fra payload. |
+| `hooks/scripts/stop-context-monitor.mjs` | Estimerer kontekst fra transcript-størrelse. Spawner pipeline ved ≥70%. |
+| `hooks/scripts/session-start-load-handoff.mjs` | Auto-leser NEXT-SESSION-fil ved resume/compact, archiverer etter load. |
+| `hooks/hooks.json` | Registrerer alle tre hooks + statusLine. |
 
-Alle handoff-filer er `*.local.md`-mønster → gitignored, ikke sporet i git.
+## Arkitektur-prinsipper
 
-## Arkitektur
+- **Hard cut fra commands/ til skills/.** v2.0 har ingen bakoverkompatibilitet.
+- **disable-model-invocation: true.** Modellen kan IKKE invokere skill-en autonomt — bruker trigger manuelt eller hooks kaller pipeline-skriptet direkte.
+- **Pipeline er deterministisk.** Tester kjører mot pipeline-skriptet uten LLM. Driftvariasjoner mellom Opus/Sonnet/Haiku elimineres for selve handoff-arbeidet.
+- **Push aldri automatisk.** Reversibel handling (commit) auto-eksekveres; irreversibel (push) krever bruker.
+- **Eksplisitt staging.** Pipeline stager kun artefakten (+ REMEMBER.md/TODO.md hvis de finnes). ALDRI `git add -A` — det scoopper opp ubeslektet WIP. Regression-test håndhever dette.
 
-Helt deklarativ — ingen hooks, ingen agents, ingen subprocess. Main-sesjonen utfører alle seks faser inline med Bash + Read/Write/Edit:
+## Auto-trigger-mekanikk
 
-1. Detekter arbeidsmappe og prosjekt (pwd, git, find)
-2. Identifiser handoff-type (multi-sesjon / plugin-arbeid / enkelt-oppgave)
-3. Skriv NEXT-SESSION-artefakt til riktig lokasjon
-4. Oppdater REMEMBER.md og TODO.md
-5. Commit + push med Conventional Commits-melding (auto-generert)
-6. Print copy-paste-prompt til terminal
+Claude Code eksponerer ikke real-time kontekst-prosent til hooks (Anthropic har closed feature requests #16988, #27969, #34340). Vi approksimerer:
+
+1. Stop hook får `transcript_path` i payload
+2. `wc -c <transcript>` → char count
+3. Tokens ≈ chars / 3.5
+4. Sammenlign mot `context_window_size` fra payload (200k default, 1M støttet)
+5. Ved ≥ 70% (estimert): spawn pipeline med `--auto --no-push --non-interactive`
+
+Lock-fil `<transcript_dir>/.handoff-lock-<session_id>` hindrer repeat-firing innen samme sesjon.
+
+## Tester
+
+```bash
+node --test plugins/graceful-handoff/tests/
+```
+
+36+ tester på tvers av 6 test-filer. Stop hook-tester bruker stub pipeline (genererer en mid-test fake `scripts/handoff-pipeline.mjs` i temp dir) for å unngå reelle git-operasjoner mot marketplace-repoet.
 
 ## Tidsbudsjett
 
-< 60 sekunder totalt. Ingen Agent-delegering, ingen WebSearch. Hvis den drar ut: bruker er allerede på kontekst-trøskelen og trenger output raskt.
+< 60 sekunder totalt for hele pipelinen. Pipeline-skriptet er testbart med `node:test` uten LLM-kall.
 
-## Begrensninger (v1.0.0)
+## Åpne antakelser (verifiseres ved smoke-test)
 
-- Ingen auto-invokasjon ved kontekst-terskel — bruker triggrer manuelt
-- Ingen backup av eksisterende NEXT-SESSION-filer (overskrives, men merger fra innhold)
-- Ingen integrasjon mot ultraplan-local progress.json (lesing, ikke skriving)
-- Commit-meldingen er auto-generert uten bekreftelse — bruk `--no-commit` hvis du vil håndtere commit manuelt
+- **statusLine-plassering i `hooks/hooks.json`** vs `~/.claude/settings.json`. Vi setter den i hooks.json som første-prioritet design.
+- **Token-estimering ±10%** mot Claude's reelle telling.
+- **Issue #26251** (`disable-model-invocation: true` regression). Smoke-test at `/graceful-handoff` fungerer etter installasjon.
+
+## Versjonering
+
+- v1.0.0 (2026-04-19): initial declarative command
+- v2.0.0 (2026-05-01): skill-arkitektur + JSON-pipeline + 3 hooks + auto-trigger (BREAKING)