Kjell Tore Guttormsen
2c4e5e425b
BREAKING: replace the NEXT-SESSION artifact + 3 hooks with a STATE.md-centric, skill-only design. /graceful-handoff now overwrites the nearest STATE.md (with the mandatory 👉 NESTE block) instead of writing a separate handover file. - Remove hooks/ entirely: Stop auto-trigger (operator choice), SessionStart loader (redundant with global session-start.sh), statusLine hint (dead — user settings win). - Invert the pipeline: the model writes STATE.md (only it has the context for 👉 NESTE); handoff-pipeline.mjs becomes a slim deterministic helper (--plan / --commit / --dry-run). - Remote-aware policy: STATE.md tracked on private remotes, local-only (gitignored) on public/open mirrors. Authoritative signal: git check-ignore STATE.md. - SKILL.md rewritten as the Session-Slutt ritual; dropped the Sonnet model pin. - Docs (README, CLAUDE.md, CHANGELOG), plugin.json 2.1.0→3.0.0, .gitignore cleanup. - Tests rewritten for --plan/--commit; no-`git add -A` regression preserved. 30/30 green. Release-cut (tag v3.0.0 + catalog ref bump) pending — separate gated action. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019SiKr4c6GAzQH5n6E6f5NA
78 lines
4.4 KiB
Markdown
78 lines
4.4 KiB
Markdown
# 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 kun i vindu → 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.
|
|
|
|
## 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 push-vindu + operatør-go.
|