signal-ckpt

# ⚡ signal-ckpt — Manual Checkpoint Collapse the session into a ≤50 token state atom. Drop all prior history. Resume from the atom. --- ## Invocation Triggers Activate when user says any of: - `/signal-ckpt` - `"checkpoint"`, `"compress context"`, `"summarize session"` - `"save state"`, `"compress history"`, `"ckpt"` - Auto-fires in SIGNAL-3 mode every 5 turns --- ## Output Format ``` CKPT[N]: §project={name} §stack={tech} progress=[{task}✓, {task}✗, {task}∅, {task}/] blockers=[{issue}⊥{component}] next={next_task} §decisions=[{decision}✓] ``` `N` = checkpoint sequence number, starting at 1. Increment on each checkpoint. **Minimal valid checkpoint (when session is simple):** ``` CKPT[1]: §project=my-app progress=[auth✓, api/] next=finish api endpoints ``` **Full checkpoint (active blockers, decisions, aliases):** ``` CKPT[3]: §project=data-pipeline §stack=python+airflow [X1]=schema_validation_step [X2]=postgres_loader progress=[ingest✓, transform✓, X1✗, X2∅] blockers=[X1⊥schema_mismatch] next=fix schema_mismatch in X1 §decisions=[use_upsert✓] ``` --- ## Hard Rules 1. **≤50 tokens total.** Count ruthlessly. If over, compress further: merge related tasks, abbreviate names, drop resolved items. 2. **Checkpoint replaces conversation history.** After this fires, all prior turns can be dropped. The checkpoint IS the history. 3. **Only active blockers.** Resolved blockers are gone. They do not appear anywhere in the checkpoint. 4. **Only future-relevant decisions.** `§decisions` only includes decisions that affect work not yet complete. Past decisions with no forward implication are dropped. 5. **`next` is singular.** One task. The most immediate pending action. Not a backlog. 6. **Carry active aliases forward.** Any `[Xn]` aliases still in use must appear in the checkpoint. Aliases for resolved items are dropped. --- ## Collapse Algorithm When generating a checkpoint: 1. **Identify all tasks** mentioned in the session. Assign each a status from its last known state (`✓` `✗` `∅` `/` `⊥`). 2. **Drop resolved blockers.** If a blocker was fixed, it's gone. 3. **Filter `§decisions`** to only those that affect future work. 4. **Set `next`** to the single most immediate pending or in-progress action. 5. **Count tokens.** If >50: - Merge related tasks (`auth-login✓ + auth-refresh✓` → `auth✓`) - Abbreviate task names (keep enough to be unambiguous) - Drop sev1/low-signal completed tasks - Omit `§stack` if obvious from project name 6. **Verify sufficiency.** Could someone read only this checkpoint and resume the work without prior context? If no, add the missing signal. --- ## Status Symbols | Symbol | Meaning | |---|---| | `✓` | Complete | | `✗` | Failed / broken | | `∅` | Not started | | `/` | In progress | | `⊥` | Blocked | --- ## Resuming from a Checkpoint When a session resumes after a checkpoint (new context window, continuation): 1. Paste the checkpoint as the **first thing** in the new context. 2. The checkpoint bootstraps full session state. 3. Resume from `next` without re-reading prior turns. 4. Aliases declared in the checkpoint are active immediately. **Resume format:** ``` [Resuming from CKPT[2]] CKPT[2]: §project=api-service §stack=node+express progress=[auth✓, routes/, tests∅] next=finish routes ``` --- ## SIGNAL-3 Auto-Checkpoint In SIGNAL-3 mode, checkpoints fire automatically every 5 turns (or the configured interval). Auto-checkpoint behavior: - Fires silently at the end of turn N (not announced before) - Output appears as the last element of the turn N response - Turn N+1 begins with the checkpoint already in context **Configuring the interval:** ``` BOOT: CKPT:every 3 turns ← more aggressive BOOT: CKPT:every 10 turns ← less aggressive BOOT: CKPT:∅ ← disable auto-checkpoint (manual only) ``` --- ## Examples ### Simple 5-turn debug session ``` CKPT[1]: §project=auth-api progress=[login-endpoint✓, refresh-endpoint/, logout∅] blockers=[refresh⊥redis_timeout] next=fix redis timeout in refresh endpoint ``` Token count: ~22 tokens. Under limit. ### Complex 15-turn architecture session ``` CKPT[3]: §project=platform-v2 §stack=nextjs+postgres+redis [X1]=auth_service [X2]=caching_layer [X3]=rate_limiter progress=[X1✓, X2/, X3∅, db-schema✓, api-routes/] blockers=[X2⊥session_store_conflict] next=resolve X2⊥session_store §decisions=[jwt_over_sessions✓, redis_for_X2✓] ``` Token count: ~38 tokens. Under limit. --- ## Eat Your Own Cooking The checkpoint itself must be maximally compressed: - No preamble ("Here is a checkpoint of our session:") - No explanation after the checkpoint atom - The checkpoint IS the output — nothing before, nothing after - If something prevents checkpoint generation: one line, TMPL:bug format