63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# graceful-handoff (v2.0)
|
|
|
|
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
|
|
|
|
- **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.
|
|
|
|
## Komponenter
|
|
|
|
| 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. |
|
|
|
|
## Arkitektur-prinsipper
|
|
|
|
- **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.
|
|
|
|
## Auto-trigger-mekanikk
|
|
|
|
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 for hele pipelinen. Pipeline-skriptet er testbart med `node:test` uten LLM-kall.
|
|
|
|
## Åpne antakelser (verifiseres ved smoke-test)
|
|
|
|
- **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)
|