40a82ccdb4
Stop hook fallback antok 200K-vindu. På Opus 4.7 (faktisk 1M) kunne auto-handoff fyre 5–7x for tidlig — estimert 70% når reell bruk var ~14%. Erstatter enkel fallback med 4-stegs resolution-kjede: 1. payload.context_window.used_percentage (autoritativ) 2. payload.context_window.context_window_size + transcript-estimat 3. MODEL_WINDOWS[payload.model.id] + estimat 4. FALLBACK_WINDOW=1_000_000 + estimat (2026-default) additionalContext-meldinger inkluderer nå [kilde: <source>] for innsyn. Brief som kilde-artefakt i docs/brief-context-window-detection.md. 6 nye tester (57 totalt). Ingen regresjoner.
65 lines
4.2 KiB
Markdown
65 lines
4.2 KiB
Markdown
# graceful-handoff (v2.1)
|
|
|
|
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 direkte til Stop hook (Anthropic har closed feature requests #16988, #27969, #34340). v2.1 bruker en **4-stegs resolution-kjede** (`resolveContextSource()` i `stop-context-monitor.mjs`):
|
|
|
|
1. `payload.context_window.used_percentage` — autoritativ, modell-agnostisk (kilde: `direct`)
|
|
2. `payload.context_window.context_window_size` + `chars/3.5`-estimat (kilde: `payload-size`)
|
|
3. `MODEL_WINDOWS[payload.model.id]` + estimat — Opus 4.7=1M, Sonnet 4.6=200k, Haiku=200k (kilde: `model-map`)
|
|
4. `FALLBACK_WINDOW = 1_000_000` + estimat — oppdatert 2026-default (kilde: `default-1m`)
|
|
|
|
Ved ≥ 70% (estimert): spawn pipeline med `--auto --no-push --non-interactive`. additionalContext-meldingen inkluderer `[kilde: <source>]` for innsyn.
|
|
|
|
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)
|
|
- v2.1.0 (2026-05-01): modell-bevisst kontekstvindu — 4-stegs resolution-kjede (used_percentage → payload-size → model-map → 1M default). Fikser for-tidlig auto-handoff på Opus 4.7
|