feat(graceful-handoff): sync the ritual with the global session-end mechanism (v3.2.0)
SKILL.md had drifted from the global CLAUDE.md on two counts, both verified by grep before the rewrite: the STATE.md template predated the mandatory `board:` line and the `route:`/`route-last:` lines, and the closing line still demanded three fields where six are now required (Innboks, Modell neste okt, Oppstartskommando were missing). - New step 3 routes the next session via `repo-mailbox:route` BEFORE the Write. It cannot run after the commit: the emitted lines live inside STATE.md, so routing afterwards would dirty a file that was just committed. One invocation feeds both the three comment lines and the closing line's model fields. - `repo-mailbox` stays a soft dependency — documented fallback if it is absent or the cross-plugin Skill invocation is blocked. `route.sh`'s path is deliberately not hardcoded (plugin cache, versioned, drifts). - The single-line constraint on the three comments is now in prose: `board.sh` reads the first non-blank, non-heading, non-`<!--` line under the heading as the repo's next step, so a wrapped `rationale=` corrupts the board. - Closing line 3 -> 6 fields. The Innboks field reports what the session did rather than re-querying the mailbox — inbox handling belongs first in a session, and "no inbox injected" must never be reported as "empty". - STATE format consolidated to ONE copy. Repo CLAUDE.md restated it with the same defect; it now points at SKILL.md step 4 as the authority, following the model-rubric precedent (two copies drift, prose cannot be tested). - allowed-tools gains `Skill`. `plugin.json` description left unchanged on purpose — editing it would require the manual marketplace.json edit that release-plugin.mjs does not perform. Tests 30 -> 42, all green. They are prose greps: drift guards, not proof the ritual runs. Verifying that means a manual /graceful-handoff against a scratch repo. Release (tag + catalog ref bump) is operator-gated and NOT done here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013V59bNbWa5x2oTH2NMBJy4
This commit is contained in:
parent
9f84234440
commit
96a22474bd
7 changed files with 202 additions and 30 deletions
|
|
@ -1,6 +1,6 @@
|
||||||
{
|
{
|
||||||
"name": "graceful-handoff",
|
"name": "graceful-handoff",
|
||||||
"version": "3.1.0",
|
"version": "3.2.0",
|
||||||
"description": "One-command session handoff into the STATE.md continuity system. /graceful-handoff reaches a natural stopping point, overwrites the nearest STATE.md with a complete state-of-play (mandatory '👉 NESTE' block), and commits per remote policy (private → tracked, public mirror → local-only). Skill-only, deterministic STATE helper, no hooks.",
|
"description": "One-command session handoff into the STATE.md continuity system. /graceful-handoff reaches a natural stopping point, overwrites the nearest STATE.md with a complete state-of-play (mandatory '👉 NESTE' block), and commits per remote policy (private → tracked, public mirror → local-only). Skill-only, deterministic STATE helper, no hooks.",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "Kjell Tore Guttormsen"
|
"name": "Kjell Tore Guttormsen"
|
||||||
|
|
|
||||||
18
CHANGELOG.md
18
CHANGELOG.md
|
|
@ -4,10 +4,26 @@ All notable changes to graceful-handoff are documented here.
|
||||||
|
|
||||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||||
|
|
||||||
## [Unreleased]
|
## [3.2.0] - 2026-08-09
|
||||||
|
|
||||||
### Changed
|
### Changed
|
||||||
|
|
||||||
|
- **The ritual is back in sync with the global "Session Slutt" mechanism.** SKILL.md had drifted: its STATE.md template predated the mandatory `board:` line and the `route:` / `route-last:` lines, and its closing line still demanded three fields where the global CLAUDE.md now requires six. Both are fixed, and the ordering matters — see below.
|
||||||
|
- **New step 3: route the next session *before* STATE.md is written.** The ritual now invokes the `repo-mailbox:route` skill between `--plan` and the Write. It cannot run after the commit: the emitted lines live *inside* STATE.md, so routing afterwards would dirty a file that was just committed. One invocation feeds two consumers — the three comment lines in the template, and the `Modell neste økt` / `Oppstartskommando` fields in the closing line. Deriving the model by hand in the closing line is exactly what the lookup exists to prevent.
|
||||||
|
- **`repo-mailbox` is a soft dependency.** The plugin is separately installable, so step 3 documents a fallback: if `repo-mailbox` is absent (or the cross-plugin `Skill` invocation is blocked), the ritual continues, fills `next-cost` by judgement, and says so explicitly rather than passing it off as a rubric lookup. `route.sh`'s path is deliberately **not** hardcoded — it sits in the plugin cache behind a version number that drifts.
|
||||||
|
- **The template now carries the single-line constraint in prose, not just by example.** `board.sh` reads the first line under the `👉 NESTE` heading that is non-blank, non-heading and does not *start* with `<!--`, and shows it as that repo's next step across every repo — so a `rationale=` wrapped across two lines replaces the repo's next step on the board with garbage.
|
||||||
|
- **Closing line: 3 fields → 6.** Added `Innboks`, `Modell neste økt` and `Oppstartskommando`. The inbox field **reports what the session did** rather than re-querying the mailbox: inbox handling belongs first in a session, and a fresh read at handoff time surfaces messages too late to act on. A new light step 7 makes the distinction explicit, including that "no inbox was injected" must never be reported as "empty ✅".
|
||||||
|
- **STATE.md format consolidated to one copy.** The repo's own `CLAUDE.md` restated the format — with the same missing lines, the identical defect in a second location. It now points at SKILL.md step 4 as the authority instead, following the precedent set when the model rubric was removed from the global CLAUDE.md: two copies drift, and prose in a doc file cannot be tested.
|
||||||
|
- `allowed-tools` gains `Skill` (needed to invoke `repo-mailbox:route`). `Bash` stays sub-scoped; `curl`/`wget` remain unapproved.
|
||||||
|
- **`plugin.json`'s `description` is deliberately unchanged** — it is still accurate, and editing it would require the manual `marketplace.json` description edit that `release-plugin.mjs` does not perform.
|
||||||
|
|
||||||
|
### Tests
|
||||||
|
|
||||||
|
- 30 → 42. Eleven new guards in `skill-structure.test.mjs` (all three comment lines present, closed status-token set, single-line warning, `repo-mailbox:route` referenced, route step ordered *before* the Write, documented fallback, all six closing-line fields, the "three items" phrasing gone, the inbox honesty rule, and repo `CLAUDE.md` deferring to SKILL.md) plus the version/CHANGELOG pins in `plugin-manifest.test.mjs`.
|
||||||
|
- **These are prose greps — drift guards, not correctness proofs.** None of them executes the ritual. Verifying it means running `/graceful-handoff` manually against a scratch repo.
|
||||||
|
|
||||||
|
### Changed (documentation, released with this version)
|
||||||
|
|
||||||
- **README brought in line with the org repo standard** (`repo-standard` gate, 0 ERROR). Documentation only — no plugin code, version, or behaviour changed. H1 is now the repo name; the opening line is verbatim the forge description (so description == catalog == README is machine-checkable); `## Install` is a top-level heading on the first screen and carries the CLI command `claude plugin install graceful-handoff@ktg-plugin-marketplace` next to `marketplace add`; `## Non-goals` and `## Changelog` sections added.
|
- **README brought in line with the org repo standard** (`repo-standard` gate, 0 ERROR). Documentation only — no plugin code, version, or behaviour changed. H1 is now the repo name; the opening line is verbatim the forge description (so description == catalog == README is machine-checkable); `## Install` is a top-level heading on the first screen and carries the CLI command `claude plugin install graceful-handoff@ktg-plugin-marketplace` next to `marketplace add`; `## Non-goals` and `## Changelog` sections added.
|
||||||
- **Dropped the static `tests-30` badge.** This forge has no CI runner, so the badge asserted a run nothing verifies. The Testing section now states the command and says plainly that nothing runs it automatically. Note for the catalog: the tests axis no longer has a badge backing it.
|
- **Dropped the static `tests-30` badge.** This forge has no CI runner, so the badge asserted a run nothing verifies. The Testing section now states the command and says plainly that nothing runs it automatically. Note for the catalog: the tests axis no longer has a badge backing it.
|
||||||
- **Fixed two dead `../../README.md` references** inherited from the monorepo (README lines 7 and the marketplace footer) — both pointed outside a standalone repo and 404'd.
|
- **Fixed two dead `../../README.md` references** inherited from the monorepo (README lines 7 and the marketplace footer) — both pointed outside a standalone repo and 404'd.
|
||||||
|
|
|
||||||
34
CLAUDE.md
34
CLAUDE.md
|
|
@ -1,4 +1,4 @@
|
||||||
# graceful-handoff (v3.0)
|
# graceful-handoff (v3.2)
|
||||||
|
|
||||||
Én-kommandos sesjonsoverlevering inn i **STATE.md-kontinuitetssystemet**. `/graceful-handoff`
|
É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
|
når et naturlig stoppunkt, overskriver nærmeste `STATE.md` med en komplett state-of-play
|
||||||
|
|
@ -24,17 +24,25 @@ Bare sesjonsmodellen har konteksten til å fylle «👉 NESTE»-blokken meningsf
|
||||||
|
|
||||||
| Fil | Rolle |
|
| 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`. |
|
| `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. |
|
| `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
|
Rituelet (SKILL.md): nå naturlig stoppunkt → `--plan` → rut neste økt (`repo-mailbox:route`) →
|
||||||
→ `--commit` → push (Forgejo) → fast avslutningslinje.
|
skriv/overskriv STATE.md i fast format → `--commit` → push (Forgejo) → fast avslutningslinje.
|
||||||
|
|
||||||
## STATE.md-format (ufravikelig)
|
## STATE.md-format (ufravikelig) — ÉN kopi, og den bor i SKILL.md
|
||||||
|
|
||||||
`# STATE — <navn>` + undertittel → **`## 👉 NESTE — START HER`** ØVERST (hvor vi er + nummererte
|
Formatet sto tidligere gjengitt her. Det er **fjernet med vilje**: to kopier av samme mal drifter
|
||||||
neste steg + pekere til hva som må leses) → faste seksjoner (oppdrag/kjøremodus, gotchas,
|
fra hverandre, og en mal i en prosa-fil kan ikke testes. **Ikke gjenopprett den her.**
|
||||||
push-status, repo/env) + kort historikk UNDER. Maks ~60 linjer. Overskriv, ikke append.
|
|
||||||
|
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)
|
## Remote-policy (STATE må aldri nå et offentlig speil)
|
||||||
|
|
||||||
|
|
@ -59,11 +67,16 @@ ubeslektet WIP. Regresjonstest håndhever dette. Pre-commit hooks respekteres ut
|
||||||
node --test 'tests/**/*.test.mjs'
|
node --test 'tests/**/*.test.mjs'
|
||||||
```
|
```
|
||||||
|
|
||||||
30 tester på tvers av 3 filer (`skill-structure`, `scripts/handoff-pipeline`, `plugin-manifest`).
|
42 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,
|
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,
|
remote-klassifisering, staging-disiplin (no-`git add -A`-regresjon), gitignored-STATE-skip, detached-HEAD,
|
||||||
`--dry-run`.
|
`--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. Den faktiske verifiseringen er
|
||||||
|
en manuell `/graceful-handoff` mot et scratch-repo; grønne tester er ikke det samme som et
|
||||||
|
verifisert ritual.
|
||||||
|
|
||||||
## Versjonering
|
## Versjonering
|
||||||
|
|
||||||
- v1.0.0 (2026-04-19): deklarativ command, NEXT-SESSION-artefakt
|
- v1.0.0 (2026-04-19): deklarativ command, NEXT-SESSION-artefakt
|
||||||
|
|
@ -71,9 +84,10 @@ remote-klassifisering, staging-disiplin (no-`git add -A`-regresjon), gitignored-
|
||||||
- v2.1.0 (2026-05-01): modell-bevisst kontekstvindu (4-stegs resolution-kjede)
|
- 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.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.1.0 (2026-06-24): fjernet hardkodet push-vindu — push er nå ubetinget (kun Forgejo, fortsatt user-triggered).
|
||||||
|
- 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)
|
## 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)
|
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 med `check-versions.mjs` grønn. Bruk
|
katalogens `ref` bumpet til samme tag med `check-versions.mjs` grønn. Bruk
|
||||||
`../catalog/scripts/release-plugin.mjs graceful-handoff <versjon>` (atomisk). Krever operatør-go.
|
`../catalog/scripts/release-plugin.mjs graceful-handoff <versjon>` (atomisk). Krever operatør-go.
|
||||||
|
|
|
||||||
10
README.md
10
README.md
|
|
@ -6,7 +6,7 @@ One-command session handoff into the STATE.md continuity system. Overwrites the
|
||||||
|
|
||||||
*AI-generated: all code produced by Claude Code through dialog-driven development. Every change is human-directed, reviewed, and validated before commit. Per Anthropic Consumer Terms §4, ownership of outputs is assigned to the user.*
|
*AI-generated: all code produced by Claude Code through dialog-driven development. Every change is human-directed, reviewed, and validated before commit. Per Anthropic Consumer Terms §4, ownership of outputs is assigned to the user.*
|
||||||
|
|
||||||

|

|
||||||

|

|
||||||

|

|
||||||

|

|
||||||
|
|
@ -269,16 +269,18 @@ Enforced by tests, not convention:
|
||||||
node --test 'tests/**/*.test.mjs'
|
node --test 'tests/**/*.test.mjs'
|
||||||
```
|
```
|
||||||
|
|
||||||
30 tests across 3 files:
|
42 tests across 3 files:
|
||||||
|
|
||||||
| File | Coverage |
|
| File | Coverage |
|
||||||
|------|----------|
|
|------|----------|
|
||||||
| `tests/skill-structure.test.mjs` | SKILL.md frontmatter (no `model:` pin, `Write` in allowed-tools, `disable-model-invocation`), `👉 NESTE` mandate, removal of `commands/` and `hooks/` |
|
| `tests/skill-structure.test.mjs` | SKILL.md frontmatter (no `model:` pin, `Write` + `Skill` in allowed-tools, `disable-model-invocation`), `👉 NESTE` mandate, the three STATE header comment lines + their single-line constraint, route-before-write ordering, the six closing-line fields, removal of `commands/` and `hooks/` |
|
||||||
| `tests/scripts/handoff-pipeline.test.mjs` | `--plan`/`--commit`/`--dry-run`, nearest-STATE resolution, remote classification, **no-`git add -A` regression**, gitignored-STATE skip, detached HEAD |
|
| `tests/scripts/handoff-pipeline.test.mjs` | `--plan`/`--commit`/`--dry-run`, nearest-STATE resolution, remote classification, **no-`git add -A` regression**, gitignored-STATE skip, detached HEAD |
|
||||||
| `tests/plugin-manifest.test.mjs` | plugin.json version + description, CHANGELOG `[3.0.0]` BREAKING + preserved history |
|
| `tests/plugin-manifest.test.mjs` | plugin.json version + description, CHANGELOG `[3.2.0]` and `[3.0.0]` BREAKING + preserved history |
|
||||||
|
|
||||||
The suite runs in a few seconds — no LLM involvement. **Nothing runs it automatically:** this forge has no CI runner, so the command above from a clean clone is the only verification. That is also why this README carries no test badge — a static one would assert a run nobody performed.
|
The suite runs in a few seconds — no LLM involvement. **Nothing runs it automatically:** this forge has no CI runner, so the command above from a clean clone is the only verification. That is also why this README carries no test badge — a static one would assert a run nobody performed.
|
||||||
|
|
||||||
|
**What the ritual tests do and do not prove.** The `skill-structure` checks are prose greps over `SKILL.md` — drift guards that catch the file falling out of step with the global session-end convention. None of them executes the ritual. Verifying the ritual itself means running `/graceful-handoff` manually against a scratch repo.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## What Changed in v3.0 (BREAKING)
|
## What Changed in v3.0 (BREAKING)
|
||||||
|
|
|
||||||
|
|
@ -3,10 +3,10 @@ name: graceful-handoff
|
||||||
description: Avslutt sesjonen kontrollert og overlever til neste. Nå første naturlige stoppunkt, overskriv nærmeste STATE.md komplett (med «👉 NESTE — START HER»-blokk), commit per remote-policy, og skriv den faste avslutningslinjen. Bruk når du vil overlevere uten kontekst-tap.
|
description: Avslutt sesjonen kontrollert og overlever til neste. Nå første naturlige stoppunkt, overskriv nærmeste STATE.md komplett (med «👉 NESTE — START HER»-blokk), commit per remote-policy, og skriv den faste avslutningslinjen. Bruk når du vil overlevere uten kontekst-tap.
|
||||||
argument-hint: "[--no-commit] [--dry-run]"
|
argument-hint: "[--no-commit] [--dry-run]"
|
||||||
disable-model-invocation: true
|
disable-model-invocation: true
|
||||||
allowed-tools: Bash(git:*) Bash(node:*) Bash(date:*) Read Write Edit Glob
|
allowed-tools: Bash(git:*) Bash(node:*) Bash(date:*) Read Write Edit Glob Skill
|
||||||
---
|
---
|
||||||
|
|
||||||
# Graceful Handoff — STATE.md-sesjonsoverlevering (v3.0)
|
# Graceful Handoff — STATE.md-sesjonsoverlevering (v3.2)
|
||||||
|
|
||||||
Dette er **én-kommandos-eksekvering av «Session Slutt»-rituelen** fra den globale
|
Dette er **én-kommandos-eksekvering av «Session Slutt»-rituelen** fra den globale
|
||||||
CLAUDE.md, sentrert på STATE.md. Du (modellen) har full sesjonskontekst — bare du
|
CLAUDE.md, sentrert på STATE.md. Du (modellen) har full sesjonskontekst — bare du
|
||||||
|
|
@ -15,7 +15,8 @@ deterministisk skript (`scripts/handoff-pipeline.mjs`) gjør kun de mekaniske bi
|
||||||
resolverer nærmeste STATE.md, klassifiserer remoten (privat → tracked, offentlig/`open/`
|
resolverer nærmeste STATE.md, klassifiserer remoten (privat → tracked, offentlig/`open/`
|
||||||
→ local-only), og committer trygt (KUN STATE.md, aldri `git add -A`).
|
→ local-only), og committer trygt (KUN STATE.md, aldri `git add -A`).
|
||||||
|
|
||||||
**Tidsbudsjett:** hele rituelet under 60 sekunder. Ingen Agent-delegering, ingen WebSearch.
|
**Tidsbudsjett:** hele rituelet på et par minutter — steg 3 (routing) er det eneste som
|
||||||
|
koster tenkning. Ingen Agent-delegering, ingen WebSearch.
|
||||||
|
|
||||||
## Hvorfor STATE.md (ikke en NEXT-SESSION-artefakt)
|
## Hvorfor STATE.md (ikke en NEXT-SESSION-artefakt)
|
||||||
|
|
||||||
|
|
@ -51,7 +52,24 @@ Parse JSON:
|
||||||
Hvis `errors[]` ikke er tom: rapporter og stopp. Hvis `leak_warning` er satt: nevn det
|
Hvis `errors[]` ikke er tom: rapporter og stopp. Hvis `leak_warning` er satt: nevn det
|
||||||
for bruker (STATE.md burde vært gitignored på denne remoten).
|
for bruker (STATE.md burde vært gitignored på denne remoten).
|
||||||
|
|
||||||
### 3. Skriv/overskriv STATE.md — UFRAVIKELIG FORMAT
|
### 3. Rut neste økt (FØR du skriver STATE.md)
|
||||||
|
Bestem først HVA «👉 NESTE» skal si — selve arbeidet neste økt skal gjøre. Så scorer du
|
||||||
|
den oppgaven med **`repo-mailbox:route`**-skillen (Skill-verktøyet). Rekkefølgen er ikke
|
||||||
|
valgfri: routingen produserer linjer som skal STÅ I fila du skriver i steg 4. Rutes det
|
||||||
|
etterpå, skitner du til en STATE.md du allerede har committet.
|
||||||
|
|
||||||
|
Én invokering dekker to forbrukere:
|
||||||
|
1. de tre kommentar-linjene i STATE-malen under (`board` / `route` / `route-last`), og
|
||||||
|
2. feltene **Modell neste økt** + **Oppstartskommando** i avslutningslinjen (steg 8).
|
||||||
|
|
||||||
|
Ikke utled modellen for hånd i steg 8 — det er nøyaktig det oppslaget finnes for. Splei
|
||||||
|
`next-cost` inn i board-linjen; `status` og `blocked-on` er dine, skillen kan dem ikke.
|
||||||
|
|
||||||
|
**Hvis `repo-mailbox` ikke er installert** (eller Skill-invokeringen blokkeres): fortsett
|
||||||
|
rituelet. Behold linjene i malen, fyll `next-cost` etter eget skjønn, og si eksplisitt i
|
||||||
|
avslutningslinjen at modellvalget er en vurdering — ikke et rubrikk-oppslag.
|
||||||
|
|
||||||
|
### 4. Skriv/overskriv STATE.md — UFRAVIKELIG FORMAT
|
||||||
Skriv `state_path` (Write, overskriv — ALDRI append). Maks ~60 linjer (kun første 160
|
Skriv `state_path` (Write, overskriv — ALDRI append). Maks ~60 linjer (kun første 160
|
||||||
injiseres). Struktur, i denne rekkefølgen:
|
injiseres). Struktur, i denne rekkefølgen:
|
||||||
|
|
||||||
|
|
@ -60,6 +78,9 @@ injiseres). Struktur, i denne rekkefølgen:
|
||||||
_Current state-of-play. Overskrives (ikke append) ved sesjonsslutt. Historikk → git._
|
_Current state-of-play. Overskrives (ikke append) ved sesjonsslutt. Historikk → git._
|
||||||
|
|
||||||
## 👉 NESTE — START HER
|
## 👉 NESTE — START HER
|
||||||
|
<!-- board: status=<planned|in-progress|blocked|deferred|done>; blocked-on=<repo|->; next-cost=<modell/effort> -->
|
||||||
|
<!-- route: path=…; verification=…; reversibility=…; scope=…; rationale=… -->
|
||||||
|
<!-- route-last: model=…; effort=…; completed=<yes|no>; corrections=<n> -->
|
||||||
**<én setning: hvor vi er + hva som er neste konkrete handling>**
|
**<én setning: hvor vi er + hva som er neste konkrete handling>**
|
||||||
1. **(du/meg)** <konkret steg>
|
1. **(du/meg)** <konkret steg>
|
||||||
2. **(du/meg)** <konkret steg>
|
2. **(du/meg)** <konkret steg>
|
||||||
|
|
@ -75,13 +96,21 @@ _Current state-of-play. Overskrives (ikke append) ved sesjonsslutt. Historikk
|
||||||
Krav til innholdet:
|
Krav til innholdet:
|
||||||
- **👉 NESTE øverst, alltid** — rett etter tittel+undertittel, FØR alt annet. Den bærer
|
- **👉 NESTE øverst, alltid** — rett etter tittel+undertittel, FØR alt annet. Den bærer
|
||||||
det handlingsrettede. Operatøren skal aldri måtte lete.
|
det handlingsrettede. Operatøren skal aldri måtte lete.
|
||||||
|
- **De tre kommentar-linjene MÅ stå på ÉN linje hver** — aldri brutt over flere, aldri
|
||||||
|
som YAML-blokk. `board.sh` leser første linje under overskriften som ikke er blank,
|
||||||
|
ikke en overskrift og ikke starter med `<!--`, og viser den som repoets neste steg på
|
||||||
|
tvers av alle repo. En brukket `rationale=` erstatter derfor neste steg på tavlen med
|
||||||
|
søppel. `route-last` utelates helt hvis ett av de fire feltene er ukjent — en gjettet
|
||||||
|
verdi leses tilbake senere som en måling.
|
||||||
|
- **Board-linjen er den eneste kilden til hvem repoet venter PÅ** (`blocked-on`).
|
||||||
|
Innboks-tall betyr det motsatte: at andre venter på DEG.
|
||||||
- Konkret, ikke vagt. «Kjør `node --test tests/`, bekreft grønn, så release-cut» — ikke
|
- Konkret, ikke vagt. «Kjør `node --test tests/`, bekreft grønn, så release-cut» — ikke
|
||||||
«fortsett arbeidet».
|
«fortsett arbeidet».
|
||||||
- Skill mellom verifisert og antatt. Aldri skriv «gå til X» med mindre X eksisterer.
|
- Skill mellom verifisert og antatt. Aldri skriv «gå til X» med mindre X eksisterer.
|
||||||
- `[[memory-slug]]`-lenker til relevante auto-memory-fakta der det hjelper.
|
- `[[memory-slug]]`-lenker til relevante auto-memory-fakta der det hjelper.
|
||||||
- Selvtilstrekkelig for kald start: en fersk sesjon som KUN leser STATE.md skal vite nok.
|
- Selvtilstrekkelig for kald start: en fersk sesjon som KUN leser STATE.md skal vite nok.
|
||||||
|
|
||||||
### 4. Commit (med mindre `--no-commit` eller `--dry-run`)
|
### 5. Commit (med mindre `--no-commit` eller `--dry-run`)
|
||||||
```bash
|
```bash
|
||||||
node ${CLAUDE_PLUGIN_ROOT}/scripts/handoff-pipeline.mjs --commit [--also <relatert-fil>...] [-m "melding"]
|
node ${CLAUDE_PLUGIN_ROOT}/scripts/handoff-pipeline.mjs --commit [--also <relatert-fil>...] [-m "melding"]
|
||||||
```
|
```
|
||||||
|
|
@ -92,7 +121,7 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/handoff-pipeline.mjs --commit [--also <relate
|
||||||
ev. kode-endringer (via `--also`) og sier fra at STATE er local-only.
|
ev. kode-endringer (via `--also`) og sier fra at STATE er local-only.
|
||||||
- Pre-commit hooks respekteres — aldri `--no-verify`.
|
- Pre-commit hooks respekteres — aldri `--no-verify`.
|
||||||
|
|
||||||
### 5. Push (Forgejo, aldri automatisk utenfor handoff)
|
### 6. Push (Forgejo, aldri automatisk utenfor handoff)
|
||||||
Push er fritt — ingen ukedag/tidspunkt-gate. Etter `--commit`:
|
Push er fritt — ingen ukedag/tidspunkt-gate. Etter `--commit`:
|
||||||
- `git push origin <branch>` — **kun Forgejo, ALDRI GitHub**.
|
- `git push origin <branch>` — **kun Forgejo, ALDRI GitHub**.
|
||||||
- Hvis et repo har gitignored STATE.md (offentlig/`open/`-remote) committes/pushes kun
|
- Hvis et repo har gitignored STATE.md (offentlig/`open/`-remote) committes/pushes kun
|
||||||
|
|
@ -100,15 +129,34 @@ Push er fritt — ingen ukedag/tidspunkt-gate. Etter `--commit`:
|
||||||
- Skillen pusher kun innenfor en bruker-invokert handoff (den er
|
- Skillen pusher kun innenfor en bruker-invokert handoff (den er
|
||||||
`disable-model-invocation: true`) — aldri spontant.
|
`disable-model-invocation: true`) — aldri spontant.
|
||||||
|
|
||||||
### 6. MEMORY.md-sjekk (lett)
|
### 7. Lette sluttsjekker
|
||||||
Hvis auto-memory `MEMORY.md` finnes og er > 200 linjer: varsle bruker (flytt detalj til
|
- **MEMORY.md:** hvis auto-memory `MEMORY.md` finnes og er > 200 linjer: varsle bruker
|
||||||
topic-filer). Ikke auto-rediger den her.
|
(flytt detalj til topic-filer). Ikke auto-rediger den her.
|
||||||
|
- **Innboks:** gjør opp status for coord-meldingene DENNE økten faktisk fikk injisert —
|
||||||
|
hver skal ha nådd en terminaltilstand (besvart med `coord-send --reply-to`, eller
|
||||||
|
markert håndtert med `coord-done`). Ligger én igjen, er det lov, men det skal uttales
|
||||||
|
med begrunnelse. **Ikke re-spør postkassen her:** innboksen håndteres FØRST i en økt,
|
||||||
|
ikke ved avslutning — et ferskt oppslag på dette tidspunktet finner meldinger for sent
|
||||||
|
til å gjøre noe med. Du rapporterer hva økten gjorde, ikke hva som ligger der nå.
|
||||||
|
Ble **ingen innboks injisert** (eller er `repo-mailbox` ikke installert), skriv nettopp
|
||||||
|
det — aldri «tom ✅» om noe du aldri så.
|
||||||
|
|
||||||
### 7. Avslutningslinje (FAST — droppes aldri)
|
### 8. Avslutningslinje (FAST — droppes aldri)
|
||||||
Avslutt svaret med eksakt tre ting (speiler den globale avslutningsinstruksen):
|
Avslutt svaret med eksakt disse seks tingene, i denne rekkefølgen (speiler den globale
|
||||||
|
avslutningsinstruksen — ingen av dem er valgfrie):
|
||||||
- **STATE.md:** oppdatert ✅ + sti (eller «ikke endret» + hvorfor).
|
- **STATE.md:** oppdatert ✅ + sti (eller «ikke endret» + hvorfor).
|
||||||
|
- **Innboks:** tom ✅ / «ingen innboks ble injisert denne økten» / «N ubesvart» + hvorfor
|
||||||
|
hver enkelt ble liggende.
|
||||||
- **Neste sesjon:** den konkrete første handlingen (samme tekst som 👉 NESTE-blokken).
|
- **Neste sesjon:** den konkrete første handlingen (samme tekst som 👉 NESTE-blokken).
|
||||||
- **Commit/push:** hash + pushet/parkert-status.
|
- **Commit/push:** hash + pushet/parkert-status.
|
||||||
|
- **Modell neste økt:** `next-cost` fra steg 3 + fallback én rad billigere, og hvilken
|
||||||
|
regel som slo til (f.eks. «path=partial») — så valget er etterprøvbart.
|
||||||
|
- **Oppstartskommando:** `command`-strengen fra steg 3, i egen kodeblokk, med `/exit`
|
||||||
|
nevnt. **Aldri `cd` foran** (én repo per terminal-tab). Hører neste steg hjemme i et
|
||||||
|
ANNET repo, si det i klartekst — det er en annen tab. Lim `--advisor`-flagget inn
|
||||||
|
verbatim slik det kom; aldri legg det til på egen hånd. Holder `/clear` (samme modell
|
||||||
|
OG samme advisor som nå), si det i stedet — men husk at bare en ny prosess plukker opp
|
||||||
|
nyinstallerte plugins/skills.
|
||||||
|
|
||||||
## Flagg
|
## Flagg
|
||||||
|
|
||||||
|
|
@ -124,3 +172,10 @@ Avslutt svaret med eksakt tre ting (speiler den globale avslutningsinstruksen):
|
||||||
- Remote-klassifisering er heuristisk (`open/`/`github` → offentlig). Den autoritative
|
- Remote-klassifisering er heuristisk (`open/`/`github` → offentlig). Den autoritative
|
||||||
commit-beslutningen er likevel `git check-ignore STATE.md` — så feilklassifisering
|
commit-beslutningen er likevel `git check-ignore STATE.md` — så feilklassifisering
|
||||||
fører ikke til lekkasje, kun til et `leak_warning` hvis konfigurasjonen er inkonsistent.
|
fører ikke til lekkasje, kun til et `leak_warning` hvis konfigurasjonen er inkonsistent.
|
||||||
|
- **`repo-mailbox` er en myk avhengighet, ikke en hard.** Steg 3 invokerer
|
||||||
|
`repo-mailbox:route` via Skill-verktøyet. To ting er ikke verifisert her: at
|
||||||
|
`repo-mailbox` i det hele tatt er installert i et gitt repo, og at en `Skill`-oppføring
|
||||||
|
i `allowed-tools` faktisk slipper gjennom en kryss-plugin-invokering fra en sub-scopet
|
||||||
|
skill. Begge feiler likt og håndteres likt — fallback-stien i steg 3. Rituelet skal
|
||||||
|
aldri stoppe på dette. Skriptstien til `route.sh` er bevisst IKKE hardkodet: den ligger
|
||||||
|
i plugin-cachen bak et versjonsnummer som drifter.
|
||||||
|
|
|
||||||
|
|
@ -10,9 +10,16 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||||
const MANIFEST = join(__dirname, '..', '.claude-plugin', 'plugin.json');
|
const MANIFEST = join(__dirname, '..', '.claude-plugin', 'plugin.json');
|
||||||
const CHANGELOG = join(__dirname, '..', 'CHANGELOG.md');
|
const CHANGELOG = join(__dirname, '..', 'CHANGELOG.md');
|
||||||
|
|
||||||
test('plugin.json version is 3.1.0', () => {
|
test('plugin.json version is 3.2.0', () => {
|
||||||
const m = JSON.parse(readFileSync(MANIFEST, 'utf-8'));
|
const m = JSON.parse(readFileSync(MANIFEST, 'utf-8'));
|
||||||
assert.equal(m.version, '3.1.0');
|
assert.equal(m.version, '3.2.0');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('CHANGELOG has a [3.2.0] entry describing the ritual sync', () => {
|
||||||
|
const c = readFileSync(CHANGELOG, 'utf-8');
|
||||||
|
const match = c.match(/## \[3\.2\.0\][\s\S]*?(?=## \[3\.1\.0\]|$)/);
|
||||||
|
assert.ok(match, '[3.2.0] section missing');
|
||||||
|
assert.match(match[0], /route/);
|
||||||
});
|
});
|
||||||
|
|
||||||
test('plugin.json description mentions STATE.md', () => {
|
test('plugin.json description mentions STATE.md', () => {
|
||||||
|
|
|
||||||
|
|
@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url';
|
||||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||||
const PLUGIN_ROOT = join(__dirname, '..');
|
const PLUGIN_ROOT = join(__dirname, '..');
|
||||||
const SKILL = join(PLUGIN_ROOT, 'skills', 'graceful-handoff', 'SKILL.md');
|
const SKILL = join(PLUGIN_ROOT, 'skills', 'graceful-handoff', 'SKILL.md');
|
||||||
|
const REPO_CLAUDE_MD = join(PLUGIN_ROOT, 'CLAUDE.md');
|
||||||
|
|
||||||
function skill() {
|
function skill() {
|
||||||
return readFileSync(SKILL, 'utf-8');
|
return readFileSync(SKILL, 'utf-8');
|
||||||
|
|
@ -67,3 +68,80 @@ test('SKILL.md is STATE.md-centric (overwrites the nearest STATE.md)', () => {
|
||||||
assert.match(s, /STATE\.md/);
|
assert.match(s, /STATE\.md/);
|
||||||
assert.match(s, /overskriv/i);
|
assert.match(s, /overskriv/i);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
// --- v3.2.0: the ritual matches the global CLAUDE.md session-end mechanism ---
|
||||||
|
|
||||||
|
test('SKILL.md allowed-tools includes Skill (needed to invoke repo-mailbox:route)', () => {
|
||||||
|
const line = skill().match(/^allowed-tools:.*$/m);
|
||||||
|
assert.ok(line, 'allowed-tools line missing');
|
||||||
|
assert.match(line[0], /\bSkill\b/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md NESTE template carries all three STATE header comment lines', () => {
|
||||||
|
const s = skill();
|
||||||
|
assert.match(s, /<!-- board: status=/);
|
||||||
|
assert.match(s, /<!-- route: path=/);
|
||||||
|
assert.match(s, /<!-- route-last: model=/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md board line template uses the closed status token set', () => {
|
||||||
|
assert.match(skill(), /planned.*in-progress.*blocked.*deferred.*done/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md warns that the three comment lines must stay single-line (board.sh)', () => {
|
||||||
|
const s = skill();
|
||||||
|
assert.match(s, /board\.sh/);
|
||||||
|
assert.match(s, /ÉN linje/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md routes the next session via the repo-mailbox route skill', () => {
|
||||||
|
assert.match(skill(), /repo-mailbox:route/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('the route step runs BEFORE STATE.md is written (lines are spliced into the file)', () => {
|
||||||
|
const s = skill();
|
||||||
|
const routeStep = s.indexOf('repo-mailbox:route');
|
||||||
|
const writeStep = s.indexOf('UFRAVIKELIG FORMAT');
|
||||||
|
assert.ok(routeStep > -1 && writeStep > -1, 'both steps must exist');
|
||||||
|
assert.ok(
|
||||||
|
routeStep < writeStep,
|
||||||
|
'route must be scored before the STATE.md Write, else the commit is dirtied afterwards'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md documents a fallback when repo-mailbox is not installed', () => {
|
||||||
|
assert.match(skill(), /ikke installert/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md closing line requires all six mandatory fields', () => {
|
||||||
|
const s = skill();
|
||||||
|
for (const field of [
|
||||||
|
'STATE.md:',
|
||||||
|
'Innboks:',
|
||||||
|
'Neste sesjon:',
|
||||||
|
'Commit/push:',
|
||||||
|
'Modell neste økt:',
|
||||||
|
'Oppstartskommando:',
|
||||||
|
]) {
|
||||||
|
assert.ok(s.includes(`**${field}**`), `closing-line field missing: ${field}`);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md no longer claims the closing line has three items', () => {
|
||||||
|
assert.doesNotMatch(skill(), /eksakt tre ting/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('SKILL.md forbids asserting an empty inbox that was never seen', () => {
|
||||||
|
assert.match(skill(), /Innboks/);
|
||||||
|
assert.match(skill(), /ingen innboks ble injisert/i);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('repo CLAUDE.md points at SKILL.md as the STATE-format authority (one copy)', () => {
|
||||||
|
const c = readFileSync(REPO_CLAUDE_MD, 'utf-8');
|
||||||
|
const section = c.match(/## STATE\.md-format[\s\S]*?(?=\n## )/);
|
||||||
|
assert.ok(section, 'STATE.md-format section missing from repo CLAUDE.md');
|
||||||
|
assert.match(section[0], /SKILL\.md/, 'section must name SKILL.md as the authority');
|
||||||
|
assert.match(section[0], /Ikke gjenopprett/, 'section must forbid restoring a second copy');
|
||||||
|
// The template must NOT be restated here — two copies drift (the model-rubric precedent).
|
||||||
|
assert.doesNotMatch(section[0], /# STATE — </, 'the template itself must not reappear here');
|
||||||
|
});
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue