Kjell Tore Guttormsen 5334097c84 fix(graceful-handoff): two defects found by the first real smoke test (v3.2.1)

The pipeline had never been run against an actual repository — every test in
the suite is either a prose-grep over SKILL.md or a unit test that asserts key
presence. Running it against scratch repos (private remote, and public `open/`
remote with and without a gitignored STATE.md) found two defects living under
a 42/42-green suite.

1. dirty_files truncated the first path. gitOk() trims every command's output,
   but `git status --porcelain` puts the worktree status in column 2, so a
   modified-but-unstaged file is " M path". The trim ate the leading space and
   the fixed slice(3) then ate the first character: app.js was reported as
   pp.js. Only the first line is affected, which is why it survived — no test
   asserted dirty_files VALUES, only that the key existed. Porcelain now goes
   through a non-trimming gitOkRaw().

2. The commit message claimed a STATE.md update it did not contain. The
   message was hardcoded to "oppdater STATE.md" regardless of what was staged.
   On every `open/` repo STATE.md is gitignored, so the handoff commit carries
   only the --also paths. Git history is the regime's long-term log; it was
   systematically wrong about its own contents.

Also promotes the leak condition from advisory to hard gate. A public remote
whose STATE.md is not yet gitignored is the state a FRESH open/ repo starts
in, and should_commit_state was true there — the ritual only mentioned
leak_warning, then committed. It now lands in errors[] (step 2 stops on a
non-empty errors[]), should_commit_state is false, and --commit refuses to
stage STATE.md. Explicit --also paths are still honoured: the gate protects
STATE.md, not the commit as a whole.

And corrects SKILL.md's justification for the single-line rule. It claimed a
wrapped rationale= replaces the board's next step with garbage; board.sh in
repo-mailbox 0.20.3 tracks a comment to its closer, so that no longer follows.
The rule stands, restated with the risk that is still real: a rationale
containing the closer sequence ends its own comment early.

Tests 42 -> 48, all six written failing first.

Still unverified: that /graceful-handoff loads as a user command (#26251), and
that a cross-plugin Skill invocation of repo-mailbox:route passes from a
sub-scoped skill. Both need the catalog ref bumped so the version is installed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RvLY4FwbzY157oVqwnkHD8

2026-08-09 21:49:08 +02:00

7.7 KiB

Raw Blame History

graceful-handoff (v3.2)

É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` og `Skill` (sistnevnte for `repo-mailbox:route`).
`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 → rut neste økt (repo-mailbox:route) → skriv/overskriv STATE.md i fast format → --commit → push (Forgejo) → fast avslutningslinje.

STATE.md-format (ufravikelig) — ÉN kopi, og den bor i SKILL.md

Formatet sto tidligere gjengitt her. Det er fjernet med vilje: to kopier av samme mal drifter fra hverandre, og en mal i en prosa-fil kan ikke testes. Ikke gjenopprett den her.

Autoriteten er skills/graceful-handoff/SKILL.md steg 4 («Skriv/overskriv STATE.md — UFRAVIKELIG FORMAT»), som er der rituelet faktisk leses fra ved kjøring, og som tests/skill-structure.test.mjs låser. Endres formatet (globalt CLAUDE.md er kilden), endres SKILL.md — og testen fanger drift.

Det ene som hører hjemme her, fordi det er en avhengighet og ikke en mal: repo-mailbox er en myk avhengighet. Steg 3 invokerer repo-mailbox:route for board-/route-linjene og for avslutningslinjens modellfelt; er den ikke installert, faller rituelet tilbake til et uttalt skjønnsvalg og fortsetter.

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. Er de to inkonsistente (offentlig remote, men STATE.md IKKE gitignored) er det fra v3.2.1 en hard gate, ikke et varsel: leak_warning legges i errors[] (rituelet stopper i steg 2), should_commit_state blir false, og --commit nekter å stage STATE.md (state-leak-blocked). Det var den tilstanden et ferskt open/-repo starter i — å bare nevne den gjorde default-stien til lekkasjestien.

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'

48 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.

Vær ærlig om hva de beviser. Ritual-testene i skill-structure er prosa-grep — de er drift-vakter, ikke korrekthetsbevis. Ingen av dem kjører rituelet. Grønne tester er ikke det samme som et verifisert ritual: smoke-testen 2026-08-09 kjørte pipelinen mot ekte scratch-repo og fant to defekter under en 42/42-grønn suite (dirty_files mistet første tegn; commit- meldingen påsto STATE-oppdatering den ikke inneholdt). Begge er fikset i v3.2.1 med test først.

Fortsatt uverifisert: at /graceful-handoff laster som user-command (issue #26251), og at kryss-plugin-Skill-invokering av repo-mailbox:route slipper gjennom fra en sub-scopet skill. Begge krever at katalogens ref er bumpet slik at versjonen faktisk er installert.

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.
v3.1.0 (2026-06-24): fjernet hardkodet push-vindu — push er nå ubetinget (kun Forgejo, fortsatt user-triggered).
v3.2.1 (2026-08-09): første ekte smoke-test. Fikset dirty_files-trunkering (gitOk().trim() spiste porcelain-linjens ledende mellomrom → app.js ble pp.js), commit-melding som påsto STATE-oppdatering på local-only-repo, og gjorde lekkasje-tilstanden til en hard gate. SKILL.md-begrunnelsen for én-linjes-regelen korrigert mot board.sh 0.20.3.
v3.2.0 (2026-08-09): ritualet synket med global «Session Slutt» — nytt route-steg (repo-mailbox:route) før STATE-skrivingen, board-/route-/route-last-linjer i malen, avslutningslinjen utvidet fra 3 til 6 felt (Innboks, Modell neste økt, Oppstartskommando), STATE-formatet konsolidert til én kopi (SKILL.md).

Release (polyrepo — egen gated handling)

En versjonsbump er ikke fullført før: (1) vX.Y.Z-tag laget + pushet i denne repoen, OG (2) katalogens ref bumpet til samme tag. Krever operatør-go.

node ../catalog/scripts/release-plugin.mjs graceful-handoff --create-tag --write --commit --push

Skriptet er dry-run uten flagg — bar invokasjon printer bare planen. De fire flaggene gjør tag

katalog-ref atomisk i én kjøring; --create-tag er ikke valgfri når taggen ennå ikke finnes (uten den stopper kjøringen med BLOCKED).

Versjonen tas fra plugin.json, og overstyres KUN med --version X.Y.Z. En bar posisjonell versjon (… graceful-handoff 3.2.0) blir stilltiende ignorert — parseArgs har allerede satt name, og argumentet starter ikke med --, så det faller ut. Det ser ut til å virke så lenge plugin.json tilfeldigvis er enig; første gang den ikke er det, slipper feil versjon gjennom.

Verifisering: node ../catalog/scripts/check-versions.mjs — kriteriet er at raden for graceful-handoff er ✓ OK, ikke at kjøringen er grønn. Skriptet exit-koder på hele katalogen, så ERROR/WARN fra andre plugins (som er andre repos ansvar) holder den rød uansett hva vi gjør.

7.7 KiB Raw Blame History