Kjell Tore Guttormsen 2c4e5e425b feat(graceful-handoff)!: integrate with STATE.md continuity system (v3.0.0)

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

2026-06-23 21:09:44 +02:00

4.4 KiB

Raw Blame History

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

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.

4.4 KiB Raw Blame History