docs(graceful-handoff): align README with marketplace standard
Plugin README rewritten from 187 to 354 lines in the same shape as ai-psychosis, llm-security, config-audit, and ms-ai-architect: - English (other plugin READMEs are English) - Standard solo-project + AI-generated disclaimers - Badges row (version, platform, skill/hooks/pipeline counts, tests, license) - Table of Contents - Mermaid architecture diagram (detection / pipeline / resumption / manual) - 4-step context resolution table (v2.1) - Components section (skill, pipeline, hooks) - Workflow examples + safety guarantees + limitations - Inline version history + Feedback & Contributing Root README graceful-handoff card updated to reflect v2.1 model-aware detection and 57-test count (was 36).
This commit is contained in:
Kjell Tore Guttormsen
parent
df6e012903
commit
1d12231748
2 changed files with 279 additions and 110 deletions
|
|
@ -150,9 +150,10 @@ Research-informed thresholds. Alerts are progressive and never blocking. Privacy
|
|||
|
||||
Auto-trigger session handoff at context threshold. Manual `/graceful-handoff` always works as backup. Built for Opus 4.7.
|
||||
|
||||
When you hit 60-70% context and have to start a new session, three things usually get rushed or forgotten: summarizing state, committing finished work, and writing a continuation prompt. v2.0 removes all three from the user's hands.
|
||||
When you hit 60-70% context and have to start a new session, three things usually get rushed or forgotten: summarizing state, committing finished work, and writing a continuation prompt. v2.0 removed all three from the user's hands; v2.1 makes context detection model-aware so auto-trigger fires at the right moment on Opus 4.7's 1M window.
|
||||
|
||||
- **Auto-trigger via Stop hook** — at estimated ≥70% context, writes artifact + commits (push remains user-triggered: irreversible operations stay manual)
|
||||
- **Model-aware context detection (v2.1)** — 4-step fallback chain (`used_percentage` → `payload-size` → `model-map` → 1M default), so Opus 4.7 no longer fires 5–7× too early
|
||||
- **statusLine hint** — display-only warning at 60% and urgent reminder at 70% (never runs git, safe per research)
|
||||
- **SessionStart auto-load** — on `--resume` / `compact`, handoff content is injected into the new session via `additionalContext`; no manual `cat` needed
|
||||
- **Skill-architecture** — `disable-model-invocation: true` so Claude can't autonomously invoke the side-effect-bearing flow; user triggers manually or hooks call the pipeline directly
|
||||
|
|
@ -162,7 +163,7 @@ When you hit 60-70% context and have to start a new session, three things usuall
|
|||
|
||||
Key command: `/graceful-handoff [topic-slug] [--no-commit] [--no-push] [--dry-run]`
|
||||
|
||||
3 hooks · 1 skill · 1 pipeline · 36 tests · BREAKING from v1.0
|
||||
3 hooks · 1 skill · 1 pipeline · 57 tests · BREAKING from v1.0
|
||||
|
||||
→ [Full documentation](plugins/graceful-handoff/README.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,111 +1,186 @@
|
|||
# graceful-handoff
|
||||
# Graceful Handoff Plugin for Claude Code
|
||||
|
||||
> Auto-trigger session handoff at context threshold. Manual `/graceful-handoff` always works. Designet for Opus 4.7.
|
||||
> Auto-trigger session handoff at the context threshold so long-running work survives the next session boundary. Manual `/graceful-handoff` always works as a backup.
|
||||
|
||||
**Problemet:** Opus 4.7 fyller kontekstvinduet raskt — ofte innen ~5 minutter for reelt arbeid. Når du er på 60-70% og må starte ny sesjon, er det tre manuelle steg som blir hastverk eller glemt:
|
||||
*Built for my own Claude Code workflow and shared openly for anyone who finds it useful. This is a solo project — bug reports and feature requests are welcome, but pull requests are not accepted.*
|
||||
|
||||
1. Oppsummere hvor arbeidet står (commits, lokale endringer, hva som er testet)
|
||||
2. Commite og pushe ferdig arbeid (ellers tapes det)
|
||||
3. Skrive en copy-paste-prompt som lar neste sesjon fortsette uten tap
|
||||
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
|
||||
|
||||
**v2.0 fjerner alle tre steg fra brukerens hender:**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- **statusLine-hint ved 60%** og urgent reminder ved 70% (display-only, trygt)
|
||||
- **Stop hook auto-eksekvering ved estimert ≥70%**: skriver artefakt + commit (push gjenstår — irreversibel handling beholdes manuell)
|
||||
- **SessionStart auto-load ved `source: resume`/`compact`**: handoff-innholdet injiseres automatisk i ny sesjon, ingen `cat` nødvendig
|
||||
- **Manuell `/graceful-handoff`** fungerer som backup — alltid
|
||||
A Claude Code plugin that solves a structural problem with long sessions: the context window fills (often within ~5 minutes of real work on Opus 4.7), and the user is forced to summarize, commit, and write a continuation prompt under time pressure — or skip steps and lose continuity. This plugin removes those steps from the user's hands using a deterministic JSON pipeline plus three hooks that detect the threshold, auto-execute the reversible work, and auto-load the artifact in the next session.
|
||||
|
||||
## Installasjon
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What Is This?](#what-is-this)
|
||||
- [The Problem](#the-problem)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Architecture](#architecture)
|
||||
- [How auto-trigger works](#how-auto-trigger-works)
|
||||
- [Components](#components)
|
||||
- [Commands & Arguments](#commands--arguments)
|
||||
- [Workflow Examples](#workflow-examples)
|
||||
- [Safety Guarantees](#safety-guarantees)
|
||||
- [Testing](#testing)
|
||||
- [Limitations & Open Assumptions](#limitations--open-assumptions)
|
||||
- [Version History](#version-history)
|
||||
- [License](#license)
|
||||
- [Feedback & Contributing](#feedback--contributing)
|
||||
|
||||
---
|
||||
|
||||
## What Is This?
|
||||
|
||||
Three hooks plus one skill that handle session handoff for you:
|
||||
|
||||
- **statusLine hint** at 60% and an urgent reminder at 70% — display only, always safe
|
||||
- **Stop-hook auto-execute** at estimated ≥70% — writes the artifact + creates a commit. Push remains user-triggered
|
||||
- **SessionStart auto-load** on `source: resume`/`compact` — handoff content is injected into the new session automatically; no `cat` needed
|
||||
- **Manual `/graceful-handoff`** — always works as a backup, with the same arguments
|
||||
|
||||
The skill itself is `disable-model-invocation: true`. The model cannot autonomously invoke handoff — only the user (via the slash command) or the Stop hook (which calls the pipeline script directly, not the skill) can trigger it. This is intentional: handoff is a moment that should be deliberate.
|
||||
|
||||
> [!TIP]
|
||||
> Install the plugin and forget about it. The first time the Stop hook fires, the artifact appears, a commit lands, and `git push` is yours to run when ready.
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
Opus 4.7 fills the context window quickly. On real work — file reads, tool output, agent results — a session can hit 60–70% in five minutes. When it happens, three manual steps become rushed or skipped:
|
||||
|
||||
1. Summarize the state of the work (commits, local changes, what was tested)
|
||||
2. Commit and push finished work (otherwise it is lost when the session ends)
|
||||
3. Write a copy-paste prompt that lets the next session continue without context loss
|
||||
|
||||
Doing these three things at 65% context, with the model already forgetting earlier turns, is exactly when mistakes happen. This plugin moves all three out of the critical path:
|
||||
|
||||
- **Detection** — the Stop hook estimates context usage and fires at ≥70%
|
||||
- **Reversible execution** — the artifact is written and committed automatically
|
||||
- **Irreversible execution** — `git push` stays in your hands; the plugin will never push for you
|
||||
- **Continuation** — on the next session, the artifact is auto-loaded into context
|
||||
|
||||
The ~10% gap between the 60% statusLine hint and the 70% Stop-hook trigger gives you a window to invoke `/graceful-handoff` manually if you want to control the slug or skip the commit.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.x+
|
||||
- Node.js (any recent LTS — required for hook and pipeline scripts)
|
||||
- Git repository (the pipeline detects detached HEAD and missing upstream and reports gracefully — it never crashes)
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
|
||||
# Deretter: /plugin install graceful-handoff
|
||||
```
|
||||
|
||||
## Bruk
|
||||
Or enable directly in `~/.claude/settings.json`:
|
||||
|
||||
### Manuell trigger
|
||||
|
||||
```
|
||||
/graceful-handoff
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": {
|
||||
"graceful-handoff@ktg-plugin-marketplace": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Med slug:
|
||||
The three hooks activate immediately on install. No further configuration needed.
|
||||
|
||||
### First handoff
|
||||
|
||||
Manual:
|
||||
|
||||
```
|
||||
/graceful-handoff refactor-auth
|
||||
> /graceful-handoff
|
||||
```
|
||||
|
||||
Uten auto-commit:
|
||||
Or just keep working — when context crosses the estimated 70% threshold, the Stop hook fires automatically:
|
||||
|
||||
```
|
||||
/graceful-handoff --no-commit
|
||||
⚠️ Auto-handoff utført ved estimert 72% [kilde: direct]:
|
||||
artefakt /path/NEXT-SESSION-PROMPT.local.md.
|
||||
Push gjenstår — kjør `git push` når du er klar.
|
||||
```
|
||||
|
||||
Dry-run:
|
||||
Start the next session with `claude --resume` and the artifact is loaded into context automatically.
|
||||
|
||||
```
|
||||
/graceful-handoff --dry-run
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Detection["Detection — display + auto-trigger"]
|
||||
direction LR
|
||||
SL["statusLine<br/>60% hint, 70% urgent"]
|
||||
SH["Stop hook<br/>≥70% estimated"]
|
||||
end
|
||||
|
||||
subgraph Pipeline["Deterministic pipeline (Node, no LLM)"]
|
||||
direction LR
|
||||
P["handoff-pipeline.mjs<br/>classify → write → stage → commit"]
|
||||
end
|
||||
|
||||
subgraph Resumption["Resumption — auto-load"]
|
||||
direction LR
|
||||
SS["SessionStart hook<br/>resume / compact only"]
|
||||
AR["Archive after read<br/>*.archived.local.md"]
|
||||
end
|
||||
|
||||
subgraph Manual["Manual fallback"]
|
||||
direction LR
|
||||
SK["SKILL.md<br/>disable-model-invocation: true"]
|
||||
end
|
||||
|
||||
SL -.display only.-> User
|
||||
SH -->|spawns| P
|
||||
SK -->|invokes| P
|
||||
P -->|writes| AR
|
||||
SS -->|reads| AR
|
||||
User((user)) -->|/graceful-handoff| SK
|
||||
User -->|git push| Done((done))
|
||||
```
|
||||
|
||||
Auto-mode (used internally by Stop hook):
|
||||
Three independent layers: **detection** (hooks watching context), **pipeline** (deterministic script that does the work), **resumption** (hook that loads the artifact in the next session). Each layer is testable in isolation. The pipeline has no LLM dependencies — `node:test` runs it against fixtures in <8 s.
|
||||
|
||||
```
|
||||
/graceful-handoff --auto --no-push --non-interactive
|
||||
```
|
||||
---
|
||||
|
||||
### Automatisk trigger
|
||||
## How auto-trigger works
|
||||
|
||||
Ingen handling kreves. Når kontekst krysser estimert 70%, fyrer Stop hook automatisk:
|
||||
Claude Code does not expose real-time context-percentage to hooks (Anthropic has closed feature requests [#16988](https://github.com/anthropics/claude-code/issues/16988), [#27969](https://github.com/anthropics/claude-code/issues/27969), [#34340](https://github.com/anthropics/claude-code/issues/34340)). Instead, the Stop hook uses a **4-step resolution chain** (v2.1, in `resolveContextSource()`):
|
||||
|
||||
1. Skriver `NEXT-SESSION-PROMPT.local.md`
|
||||
2. Stager kun handoff-artefakten (IKKE andre dirty filer — eksplisitt fix i v2.0)
|
||||
3. Committer
|
||||
4. **Pusher IKKE** — dette gjør du selv når du er klar
|
||||
| Step | Source | When used | Source label |
|
||||
|------|--------|-----------|--------------|
|
||||
| 1 | `payload.context_window.used_percentage` | If the field is present and > 0 | `direct` |
|
||||
| 2 | `payload.context_window.context_window_size` + transcript estimate (`chars / 3.5`) | If size > 0 but no `used_percentage` | `payload-size` |
|
||||
| 3 | `MODEL_WINDOWS[payload.model.id]` + transcript estimate | Opus 4.7 = 1 M, Sonnet 4.6 = 200 K, Haiku = 200 K | `model-map` |
|
||||
| 4 | `FALLBACK_WINDOW = 1_000_000` + transcript estimate | Last-resort default (2026-aware) | `default-1m` |
|
||||
|
||||
Ved ny sesjon (`claude --resume`), SessionStart hook leser handoff-filen automatisk og injiserer innhold i konteksten. Filen blir deretter renamet til `*.archived.local.md` for å hindre stale-load.
|
||||
When the resolved percentage is ≥ 70%, the Stop hook spawns `handoff-pipeline.mjs --auto --no-push --non-interactive` synchronously (25 s timeout, fits within the 30 s Stop-hook budget). The `additionalContext` message includes `[kilde: <source>]` so the source path is always visible.
|
||||
|
||||
## Arkitektur (v2.0)
|
||||
**Estimation drift:** Steps 2–4 use `chars / 3.5` to approximate tokens, which can drift ±10% from Claude's internal counting. The 70% threshold is conservative buffer. Step 1 (`direct`) has no drift.
|
||||
|
||||
```
|
||||
skills/graceful-handoff/SKILL.md # Frontmatter: disable-model-invocation, model: sonnet-4-6
|
||||
scripts/handoff-pipeline.mjs # Deterministisk pipeline, returnerer JSON
|
||||
hooks/scripts/statusline-monitor.mjs # Display: 60% / 70% hint
|
||||
hooks/scripts/stop-context-monitor.mjs # Auto-execute ved estimert ≥70%
|
||||
hooks/scripts/session-start-load-handoff.mjs # Auto-load på resume/compact
|
||||
hooks/hooks.json # Registrerer alt
|
||||
```
|
||||
**Lock file:** `<transcript_dir>/.handoff-lock-<session_id>` is created on first trigger to prevent repeat firing within the same session. Touch happens *before* spawning to win races on rapid Stop events.
|
||||
|
||||
`disable-model-invocation: true` betyr at Claude IKKE kan invokere skill-en autonomt — bruker må trigge manuelt eller hook må kalle pipeline-skriptet direkte (Stop hook gjør det siste).
|
||||
**Why 70% (not 65%)?** Earlier designs targeted 65%, but estimation drift and Stop-hook latency make 70% safer. Lower thresholds risk false positives that block normal continuation.
|
||||
|
||||
## Auto-trigger ved kontekst-terskel — hvordan virker det?
|
||||
---
|
||||
|
||||
Det finnes ingen Claude Code-primitiv som eksponerer real-time kontekst-prosent til hooks (Anthropic har closed feature requests #16988, #27969, #34340). Vi bruker derfor en **4-stegs resolution-kjede** (v2.1):
|
||||
## Components
|
||||
|
||||
1. **Stop hook** fyrer etter hver model-respons og får `transcript_path` + payload
|
||||
2. Resolver kontekstbruk i prioritert rekkefølge:
|
||||
- `payload.context_window.used_percentage` — autoritativ, modell-agnostisk (ingen estimering)
|
||||
- `payload.context_window.context_window_size` + transcript-estimat (`chars / 3.5`)
|
||||
- Modell-mapping: `payload.model.id` → kjent vindusstørrelse (Opus 4.7=1M, Sonnet 4.6=200k, Haiku=200k)
|
||||
- Siste fallback: 1M (oppdatert 2026-default — antar moderne modell)
|
||||
3. Ved estimert ≥ 70%: spawner pipeline synkront
|
||||
|
||||
Estimerings-pathen (steg 2-4) kan avvike ±10% fra Claude's reelle telling. **70% er konservativt valgt** — gir buffer mot drift. Direct-pathen (`used_percentage`) har ingen drift. additionalContext-meldingen viser hvilken kilde som ble brukt (`direct`/`payload-size`/`model-map`/`default-1m`) for innsyn.
|
||||
|
||||
For å hindre repeat-firing innen samme sesjon: lock-fil `<transcript_dir>/.handoff-lock-<session_id>` opprettes ved første trigger.
|
||||
|
||||
## Argumenter
|
||||
|
||||
| Argument | Beskrivelse |
|
||||
|----------|-------------|
|
||||
| `[topic-slug]` | Kebab-case slug. Med slug: `NEXT-SESSION-<slug>.local.md`. Uten: `NEXT-SESSION-PROMPT.local.md` |
|
||||
| `--no-commit` | Hopp over commit+push. Bruker håndterer commit manuelt |
|
||||
| `--no-push` | Commit OK, men ikke push (Stop hook bruker dette) |
|
||||
| `--dry-run` | Ingen filer skrives, ingen git-operasjoner |
|
||||
| `--auto` | Non-interactive, auto-Y på commit-bekreftelse (kun for hooks) |
|
||||
| `--non-interactive` | Uten `--auto`: feil; med: kjør uten prompts |
|
||||
|
||||
## Frontmatter (SKILL.md)
|
||||
### Skill — `skills/graceful-handoff/SKILL.md`
|
||||
|
||||
```yaml
|
||||
---
|
||||
|
|
@ -117,71 +192,164 @@ allowed-tools: Bash(git:*) Bash(jq:*) Bash(node:*) Bash(find:*) Bash(pwd:*) Read
|
|||
---
|
||||
```
|
||||
|
||||
**Merk:** `allowed-tools` er pre-approval, ikke restriction. Den fjerner permission-prompts for listede verktøy, men blokkerer ikke ulistede. For ekte sandbox: bruk project-level `permissions.deny` rules.
|
||||
Thin orchestration wrapper around the pipeline script. Pinned to Sonnet 4.6 to free Opus budget for the next session. `disable-model-invocation: true` prevents the model from calling the skill on its own — handoff is always user- or hook-triggered.
|
||||
|
||||
## Tidsbudsjett
|
||||
> [!NOTE]
|
||||
> `allowed-tools` is *pre-approval*, not restriction. It removes permission prompts for the listed tools but does not block other tools from being invoked. For real sandboxing, use project-level `permissions.deny` rules.
|
||||
|
||||
< 60 sekunder totalt for hele pipelinen (manuell eller auto). Pipeline-skriptet er testbart med `node:test` uten LLM-kall.
|
||||
### Pipeline — `scripts/handoff-pipeline.mjs`
|
||||
|
||||
## Eksempler
|
||||
Deterministic Node script. Returns structured JSON. No LLM dependencies. Handles:
|
||||
|
||||
**Plugin-arbeid:**
|
||||
- Classification of handoff type (`multi-sesjon` / `plugin-arbeid` / `enkelt-oppgave`) based on cwd
|
||||
- Writing the NEXT-SESSION artifact in the correct directory
|
||||
- **Explicit staging** of only the artifact (+ `REMEMBER.md` / `TODO.md` if present) — *never* `git add -A`, enforced by a regression test
|
||||
- Commit-message generation from `git diff --stat` (Conventional Commits)
|
||||
- Push (unless `--no-push`) with detached-HEAD and no-upstream detection
|
||||
- Idempotency check: 60 s cooldown on a clean tree with a recent artifact is a no-op
|
||||
|
||||
### Hooks — `hooks/scripts/`
|
||||
|
||||
| Event | Script | What it does |
|
||||
|-------|--------|--------------|
|
||||
| `statusLine` | `statusline-monitor.mjs` | Reads `context_window.used_percentage` from payload. <60% silent, 60–69% hint, ≥70% urgent reminder. Display only — never runs git (statusLine scripts are cancellable mid-flight per official docs) |
|
||||
| `Stop` | `stop-context-monitor.mjs` | Resolves context via the 4-step chain. At ≥70% spawns the pipeline with `--auto --no-push --non-interactive`. Uses a lock file to prevent repeat firing |
|
||||
| `SessionStart` | `session-start-load-handoff.mjs` | On `source: resume` or `source: compact`, finds the most recent `NEXT-SESSION-*.local.md` (cwd + 3 levels up), injects the content via `additionalContext`, archives the file (`*.archived.local.md`) to prevent stale-load on subsequent sessions |
|
||||
|
||||
Registered in `hooks/hooks.json`.
|
||||
|
||||
---
|
||||
|
||||
## Commands & Arguments
|
||||
|
||||
```
|
||||
/graceful-handoff [topic-slug] [flags]
|
||||
```
|
||||
|
||||
| Argument | Description |
|
||||
|----------|-------------|
|
||||
| `[topic-slug]` | Kebab-case slug. With slug: `NEXT-SESSION-<slug>.local.md`. Without: `NEXT-SESSION-PROMPT.local.md` |
|
||||
| `--no-commit` | Skip commit + push. Artifact is written; user handles git manually |
|
||||
| `--no-push` | Commit OK, but skip push (the Stop hook always uses this) |
|
||||
| `--dry-run` | No files written, no git operations; print what would happen |
|
||||
| `--auto` | Non-interactive, auto-Y on commit confirmation. Intended for hooks |
|
||||
| `--non-interactive` | Without `--auto`: error. With `--auto`: run without any prompts |
|
||||
|
||||
The pipeline script accepts the same flags directly (`node scripts/handoff-pipeline.mjs ...`) — useful for debugging without going through the skill.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Plugin work (auto-trigger)
|
||||
|
||||
```
|
||||
cd plugins/llm-security
|
||||
# ... arbeid frem til 65% kontekst ...
|
||||
# Auto-trigger: ved 70% fyrer Stop hook automatisk:
|
||||
# → skriver plugins/llm-security/NEXT-SESSION-PROMPT.local.md
|
||||
# → committer ARTEFAKTEN (ikke andre dirty filer)
|
||||
# → IKKE pusher (du gjør det selv)
|
||||
git push # når klar
|
||||
# ... work until ~70% context ...
|
||||
# Stop hook fires automatically:
|
||||
# → writes plugins/llm-security/NEXT-SESSION-PROMPT.local.md
|
||||
# → stages ONLY the artifact (not other dirty files)
|
||||
# → commits with auto-generated Conventional Commits message
|
||||
# → does NOT push
|
||||
git push # when you are ready
|
||||
```
|
||||
|
||||
**Manuell trigger med flagg:**
|
||||
### Manual trigger with slug
|
||||
|
||||
```
|
||||
/graceful-handoff refactor-auth --no-commit
|
||||
# → skriver plugins/<rot>/NEXT-SESSION-refactor-auth.local.md
|
||||
# → ingen git-operasjoner
|
||||
# → writes plugins/<root>/NEXT-SESSION-refactor-auth.local.md
|
||||
# → no git operations
|
||||
```
|
||||
|
||||
**Ny sesjon:**
|
||||
### New session
|
||||
|
||||
```
|
||||
claude --resume
|
||||
# SessionStart hook auto-injiserer handoff-innholdet i konteksten
|
||||
# Du kan starte å jobbe direkte
|
||||
# SessionStart hook auto-injects handoff content into context
|
||||
# Continue working immediately
|
||||
# The artifact is renamed to NEXT-SESSION-*.archived.local.md
|
||||
# so it cannot stale-load on a third session
|
||||
```
|
||||
|
||||
## Tester
|
||||
### Dry run before committing the workflow
|
||||
|
||||
```
|
||||
/graceful-handoff --dry-run
|
||||
# Pipeline prints the JSON it would produce — file paths, commit message,
|
||||
# next steps — without writing anything or touching git
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Safety Guarantees
|
||||
|
||||
These properties are enforced by tests, not by convention:
|
||||
|
||||
- **Push is never automatic.** The auto-execute path always passes `--no-push`. Irreversible operations stay in the user's hands. (`stop-context-monitor.test.mjs`)
|
||||
- **Staging is explicit.** The pipeline stages *only* the handoff artifact (and `REMEMBER.md` / `TODO.md` if present). `git add -A` is never used — a regression test (`pipeline never stages unrelated dirty files`) enforces this.
|
||||
- **Pre-commit hooks are respected.** The pipeline never bypasses with `--no-verify`. If a pre-commit hook (gitleaks, pathguard) blocks, the handoff fails and the user fixes the underlying issue.
|
||||
- **Artifacts are gitignored.** All output files match `*.local.md`, which existing repos in this marketplace already gitignore via `.gitignore` patterns.
|
||||
- **No network calls.** No WebSearch, no Agent delegation, no MCP. The pipeline is fully local.
|
||||
- **Bash sub-scoped.** Skill `allowed-tools` enumerates `Bash(git:*) Bash(jq:*) Bash(node:*) Bash(find:*) Bash(pwd:*)` — pre-approval is narrow even though it is not a sandbox.
|
||||
- **Lock file scoped to transcript directory.** Lock path is based on `dirname(transcript_path)`, not `cwd`, so it survives `cd` mid-session.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
node --test plugins/graceful-handoff/tests/
|
||||
node --test 'plugins/graceful-handoff/tests/**/*.test.mjs'
|
||||
```
|
||||
|
||||
36 tester på tvers av:
|
||||
- `skill-structure.test.mjs` — frontmatter + commands/-fjerning (8)
|
||||
- `scripts/handoff-pipeline.test.mjs` — pipeline JSON, idempotens, no-staging-regression, edge cases (11)
|
||||
- `hooks/statusline-monitor.test.mjs` — terskler, null payload, malformed JSON (9)
|
||||
- `hooks/stop-context-monitor.test.mjs` — estimering, lock-fil, stub pipeline (7)
|
||||
- `hooks/session-start-load-handoff.test.mjs` — source filter, multi-level search, archive (9)
|
||||
- `plugin-manifest.test.mjs` — plugin.json schema, CHANGELOG (6)
|
||||
57 tests across 6 files:
|
||||
|
||||
## Begrensninger og åpne antakelser
|
||||
| File | Coverage |
|
||||
|------|----------|
|
||||
| `tests/skill-structure.test.mjs` | SKILL.md frontmatter, model pin, allowed-tools shape, removal of legacy `commands/` |
|
||||
| `tests/scripts/handoff-pipeline.test.mjs` | Pipeline JSON schema, idempotency, **no-staging-regression**, detached HEAD, no-upstream, interactive y/n |
|
||||
| `tests/hooks/statusline-monitor.test.mjs` | Threshold transitions, null payload, malformed JSON, no side effects |
|
||||
| `tests/hooks/stop-context-monitor.test.mjs` | 4-step context resolution, lock file behavior, stub-pipeline isolation, env-var failure modes |
|
||||
| `tests/hooks/session-start-load-handoff.test.mjs` | Source filter (`resume`/`compact` only), multi-level search, archive after read |
|
||||
| `tests/plugin-manifest.test.mjs` | Plugin.json schema, version pin, CHANGELOG entries |
|
||||
|
||||
- **statusLine-plassering i `hooks/hooks.json`** er en åpen antakelse. Verifiser med smoke-test; fallback er å flytte til global `~/.claude/settings.json`.
|
||||
- **Token-estimering ±10%** mot Claude's reelle telling. 70%-tersklen er konservativ.
|
||||
- **Issue [#26251](https://github.com/anthropics/claude-code/issues/26251)** — `disable-model-invocation: true` regression kan blokkere user-invocation. Manuell smoke-test før du stoler på det.
|
||||
- **Push gjenstår alltid manuell.** Auto-eksekvering pusher ALDRI — irreversibel handling beholdes hos bruker.
|
||||
- Auto-trigger respekterer pre-commit hooks (secrets, pathguard) — bypasser ALDRI med `--no-verify`.
|
||||
Stop-hook tests use a **stub pipeline** (a fake `handoff-pipeline.mjs` written into a temp dir) so test runs do not invoke real git operations against the marketplace repo.
|
||||
|
||||
## Sikkerhet
|
||||
The pipeline runs in <8 s on a 2025 Mac. The full test suite runs in ~10 s.
|
||||
|
||||
- Pipeline stager **kun** handoff-artefakten + REMEMBER.md/TODO.md (hvis de finnes). Stagger ALDRI andre dirty filer (regression-test håndhever dette).
|
||||
- Filer er `*.local.md` → matches av `.gitignore`-mønstre i alle prosjekter
|
||||
- Ingen nettverks-kall (ingen WebSearch, ingen Agent-delegering)
|
||||
- Bash sub-scoped: `Bash(git:*)`, `Bash(jq:*)`, `Bash(node:*)`, `Bash(find:*)`, `Bash(pwd:*)`
|
||||
---
|
||||
|
||||
## Lisens
|
||||
## Limitations & Open Assumptions
|
||||
|
||||
MIT
|
||||
- **Token estimation drifts ±10%** against Claude's internal counting (steps 2–4 of the resolution chain). The 70% threshold is set conservatively to absorb this. Step 1 (`direct`) has no drift but requires the payload field to be present.
|
||||
- **Stop-hook payload schema is undocumented.** It is not officially confirmed that Stop payloads include `used_percentage` or `model.id` (statusLine payloads do). If both are missing, the resolver falls through to `default-1m`. The `[kilde: <source>]` label in `additionalContext` reveals which path was actually used — first real session reveals this.
|
||||
- **statusLine placement in `hooks/hooks.json` is an open assumption.** Smoke-test before relying on it; the fallback is to move it to global `~/.claude/settings.json`.
|
||||
- **Issue [#26251](https://github.com/anthropics/claude-code/issues/26251)** — `disable-model-invocation: true` may regress and block user-invocation in some Claude Code versions. Manual smoke-test before relying on it.
|
||||
- **Auto-execute does not push.** Irreversible operations stay user-triggered, by design.
|
||||
- **Compaction events are out of scope.** PreCompact fires too late (~95%) and is not configurable. The plugin targets the 60–70% window where the user can still benefit from a clean handoff.
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
| Version | Date | Highlights |
|
||||
|---------|------|------------|
|
||||
| **2.1.0** | 2026-05-01 | **Model-aware context window detection.** Replaces 200 K fallback with 4-step resolution chain (`used_percentage` → `payload-size` → `model-map` → 1 M default). Fixes 5–7× premature firing on Opus 4.7 (1 M window). All `additionalContext` messages include `[kilde: <source>]` for transparency. 6 new tests (57 total). |
|
||||
| **2.0.0** | 2026-05-01 | **Hard cut from `commands/` to `skills/`.** New deterministic pipeline (`handoff-pipeline.mjs`), three hooks (statusLine, Stop, SessionStart), `disable-model-invocation: true`, sub-scoped `allowed-tools`, explicit staging discipline (no more `git add -A`), pinned to Sonnet 4.6 (BREAKING). |
|
||||
| **1.0.0** | 2026-04-19 | Initial release — single declarative `/graceful-handoff` command, 6-phase prose workflow, three handoff types, pre-commit hook respect, <60 s time budget. |
|
||||
|
||||
Full history in [`CHANGELOG.md`](CHANGELOG.md).
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT. See [`LICENSE`](LICENSE).
|
||||
|
||||
---
|
||||
|
||||
## Feedback & Contributing
|
||||
|
||||
- **Bug reports + feature requests:** open an issue on [Forgejo](https://git.fromaitochitta.com/open/ktg-plugin-marketplace)
|
||||
- **Pull requests:** not accepted on this repo (solo project, dialog-driven development with Claude Code). Fork freely if you need to extend.
|
||||
- **Marketplace:** part of [ktg-plugin-marketplace](https://git.fromaitochitta.com/open/ktg-plugin-marketplace) — see the [root README](../../README.md) for related plugins.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue