pi-context 1.1.4 → 2.0.0

package/README.md

@@ -1,11 +1,21 @@
-# Pi Context: Agentic Context Management for the Pi
+# Pi Context: Agentic Context Management for Pi
 
-A Git-like context management tool that allows AI agents to proactively manage their context.
+An Agentic Context Management tool that helps AI agents keep long conversations focused by maintaining a clean working set: checkpoint useful anchors, inspect the active history structure, and compact noisy completed paths into state summaries.
 
-Inspired by kimi-cli d-mail, implementing lossless time travel on the Pi session tree.
+Inspired by kimi-cli d-mail, it brings lossless time travel to Pi's session tree.
 
-For the design philosophy, see the [blog post](https://blog.xlab.app/p/51d26495/)
- ([中文版本](https://blog.xlab.app/p/6a966aeb/)).
+For more on the design philosophy, see the [blog post](https://blog.xlab.app/p/51d26495/) ([中文版本](https://blog.xlab.app/p/6a966aeb/)).
+
+## Naming migration note
+
+Earlier versions used more Git-like names such as `context_tag`, `context_log`, and `context_checkout`.
+
+Current versions intentionally use conversation-native names instead:
+- `context_checkpoint`
+- `context_timeline`
+- `context_compact`
+
+These tools manage **conversation history**, not repository state. They should not be treated as Git commands or as replacements for real `git tag`, `git log`, or `git checkout`. Context navigation does not modify or roll back files, running processes, browser state, tickets, databases, or remote services.
 
 ## Installation
 
@@ -17,13 +27,13 @@ pi install npm:pi-context
 
 ### For Humans
 
-Run the command to enable ACM (**A**gentic **C**ontext **M**anagement) for the current session.
+Run the following command to enable ACM (**A**gentic **C**ontext **M**anagement) for the current session.
 
 ```bash
 /acm
 ```
 
-View detailed context window usage and token distribution with a visual dashboard. (like `claude code /context`)
+Open a visual dashboard to inspect context-window usage and token distribution (similar to `claude code /context`).
 
 ```bash
 /context
@@ -33,13 +43,13 @@ View detailed context window usage and token distribution with a visual dashboar
 
 ### For Agents
 
-This extension adds the `context-management` skill with three core tools:
+This extension adds the `context-management` skill, which guides agents to keep the active conversation as the smallest sufficient working set for the next step. It includes three core tools:
 
-1.  **🔖 Structure (`context_tag`)**
-`git tag` Create named milestones to structure your conversation history.
+1. **🔖 Anchor (`context_checkpoint`)**
+   Label a meaningful conversation node with a unique semantic checkpoint name, such as `parser-fix-start` or `timeout-investigation-search`.
 
-2.  **📊 Monitor (`context_log`)**
-`git log` Visualize your conversation history, check token usage, and see where you are in the task tree.
+2. **📊 Inspect (`context_timeline`)**
+   View the active path as a structural map of checkpoints, summaries/compactions, branch points, user turns, and current position. Use it when orientation or compact target selection depends on history shape.
 
-3.  **⏪ Compress (`context_checkout`)**
-`git checkout` Move the HEAD pointer to any tag or commit ID. Compress completed tasks into a summary to free up context window space.
+3. **⏪ Compact (`context_compact`)**
+   Create a summarized continuation branch from an earlier checkpoint, history node, or `root`. The summary should restore the useful state after the target: current task, decisions, external side effects such as changed files or remote updates, validation state, source anchors, and the explicit next step.

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "pi-context",
-  "version": "1.1.4",
-  "description": "Agentic Context Management for the Pi",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "2.0.0",
+  "description": "Agentic Context Management for Pi",
   "files": [
     "src",
     "skills",
     "README.md"
   ],
-  "scripts": {},
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
   "keywords": [
     "pi-agent",
     "pi-package",
@@ -23,9 +23,10 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "@sinclair/typebox": "^0.34.13",
-    "typescript": "^5.7.2",
-    "@earendil-works/pi-coding-agent": "latest"
+    "@earendil-works/pi-ai": "^0.75.4",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4",
+    "typescript": "^5.7.2"
   },
   "pi": {
     "extensions": [
@@ -40,5 +41,10 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ttttmr/pi-context.git"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
   }
-}
+}

package/skills/context-management/SKILL.md

@@ -1,258 +1,215 @@
 ---
 name: context-management
-description: Strategies for efficient context management using context_log, context_tag, and context_checkout. Learn when to tag, how to visualize the graph, and safe ways to squash history. Use for complex refactoring, debugging, and long conversations.
+description: Use this skill for work likely to span many turns, branches, retries, research, reading several files/webpages, plan-then-execute phases, repeated cases, debugging, or interrupted/messy threads. It guides agents to maintain a clean working set with checkpoints, timeline review, and compaction at useful continuation boundaries. Usually skip for one-shot reads, bounded summaries, direct rewrites, simple lookups, or deterministic scripts.
 ---
 
 # Context Management
 
-**CRITICAL: THIS SKILL MANAGES YOUR MEMORY. WITHOUT IT, YOU WILL FORGET.**
+Use this skill to maintain the active conversation as a useful **working set** for the next step. The goal is not to archive more history or compress more aggressively; it is to keep raw only the context that still needs direct reasoning, and carry the rest as compact task state when that is more efficient.
 
-Your context window is limited. As conversations grow, "pollution" (noise, failed attempts) degrades your reasoning.
+Core rhythm:
 
-**YOU MUST PROACTIVELY MANAGE YOUR HISTORY.**
-Do not wait for the user to tell you.
+- **checkpoint before mess**
+- **review timeline when structure affects the next decision**
+- **compact when a state summary is a better working set than the raw trail**
 
-## The Core Philosophy: Build, Perceive, Navigate
+Use only these tools:
 
-```
-Context Window = RAM (Expensive, volatile, limited)
-Context Graph  = Disk (Cheap, persistent, unlimited)
+- `context_checkpoint`
+- `context_timeline`
+- `context_compact`
 
-→ Move finished tasks from RAM to the Graph.
-```
+## Working-set model
 
-Manage your context window like a Git repository. You are the maintainer.
+Before choosing a tool, ask:
 
-1.  **BUILD the Skeleton (`context_tag`)**:
-    *   Raw conversation is a flat list. **Tags create structure.**
-    *   Without tags, `context_log` is just a list of IDs. With tags, it is a **Map**.
-2.  **PERCEIVE the State (`context_log`)**:
-    *   Check the HUD: Is "Segment Size" too big? You are drifting.
-    *   Check the Graph: Where are you? Are you in a deep branch?
-3.  **NAVIGATE & MERGE (`context_checkout`)**:
-    *   **Squash:** Convert a messy "feature branch" (thinking process) into a single "merge commit" (summary).
-    *   **Jump:** Move between tasks or retry paths without carrying baggage.
+- What am I trying to do next?
+- What facts, constraints, or artifacts must stay raw for that next action?
+- What history is useful only as a conclusion or state update?
+- What history is just process noise or stale baggage?
 
-## Quick Start: The Loop
+Classify context into three forms:
 
-Follow this cycle for every major task:
+- **Raw context:** user intent, constraints, code/log/error details, evidence, or plan text that you expect to inspect directly soon.
+- **State summary:** decisions, findings, lessons, changed files, validation status, rejected leads, and next steps that can replace raw process.
+- **Discardable process:** repetitive searches, verbose logs, abandoned hypotheses, false starts, and unrelated turns whose useful value is already captured or no longer needed.
 
-1.  **CHECK:** Verify state.
-    `context_log`
-2.  **START:** Tag the beginning with a semantic name.
-    `context_tag({ name: "<task-slug>-start" })`  // e.g., `auth-login-start`
-3.  **WORK:** Execute steps.
-4.  **MILESTONE:** Tag intermediate stable states.
-    `context_tag({ name: "<task-slug>-plan" })`  // e.g., `auth-login-plan`
-5.  **SQUASH (Autonomous):** If history becomes noisy or low-density, **Squash with Backup**.
-    *   *Action:* `context_checkout({ target: "<task-slug>-start", message: "...", backupTag: "<task-slug>-raw-history" })`
-    *   *Action (Optional):* `context_tag({ name: "<task-slug>-done" })`
-    *   *Safety:* If you need the details later, checkout the backup tag.
+If the active context is already small, coherent, and directly useful for the next step, do not manage it just to be tidy.
 
-## Tool Reference
+## When to use
 
-| Tool | Analog | Purpose | When to Use |
-| :--- | :--- | :--- | :--- |
-| `context_tag` | `git tag` | Bookmark a stable state. | Before risky changes. Before starting a new task. |
-| `context_log` | `git log` | See where you are. | When you feel lost. To find IDs for checkout. |
-| `context_checkout`| `git reset --soft` | **Time Travel / Squash.** | To undo mistakes. To compress history. |
+Use this mode when the user is asking for work that may outgrow one clean thread:
 
-## Critical Rules
+- search, research, browser work, or reading many files/logs/pages/results
+- several links or low-density webpages where only conclusions and next actions should survive
+- investigate -> decide -> execute -> validate
+- plan -> implement -> verify
+- multiple approaches, retries, failed branches, or pivots
+- repeated similar cases, tickets, reviews, or batch items
+- a main task that may be interrupted by side tasks
+- a scattered thread that should be cleaned up before continuing from a clean point
+- debugging, troubleshooting, refactoring, migration, or other code-facing work that may get noisy
 
-### Tag Wisely (Build The Skeleton)
+If one of these clearly applies, take a structural action now, usually a checkpoint. Do not merely describe the workflow. If the user has not yet provided enough task details, still create a checkpoint for the workflow shape before asking clarifying questions, and name the detected mode briefly (search/reading, planning, repeated batch, task switching/cleanup, development retry).
 
-Tags are the "Table of Contents". Name them so you can understand the history at a glance.
+Usually skip this skill for one-shot reads, bounded summaries, direct rewrites, simple fact lookup, conceptual explanation, deterministic scripts, short tasks that can stay clean, or moments where the active context is already a good working set.
 
-**Naming Formula:** `<task-slug>-<phase>`
+## Start-of-turn check
 
-*   **task-slug**: Short, kebab-case identifier for the task (e.g., `auth-login`, `db-migration`)
-*   **phase**: The stage of work (`start`, `plan`, `impl`, `done`, `fail`, `backup`)
+At the start of each new user message, classify it:
 
-| Bad (Generic) | Good (Semantic) | Why |
-| :--- | :--- | :--- |
-| `task-start` | `auth-oauth-start` | Describes WHAT task |
-| `pre-research` | `error-log-analysis-start` | Future-you knows the topic |
-| `phase-1-done` | `db-schema-plan-done` | Know which phase of which task |
-| `debug-retry` | `null-pointer-fix-retry` | What bug? |
+- **Same task / next phase**: continue; if the previous phase is complete and noisy, compact before the next phase.
+- **Correction or follow-up on the last answer**: usually answer from recent context; do not compact yet.
+- **New unrelated task or direction shift**: if the previous task left a complete noisy segment, inspect the timeline first when multiple checkpoints or possible anchors exist, then compact to a continuation anchor that gives the new task a clean working set.
 
-**Tag Categories:**
+Think of the tools as a phase pipeline: `context_checkpoint` marks useful anchors, work happens, `context_timeline` shows the structure when orientation or target choice is unclear, and `context_compact` creates a new branch from the chosen continuation anchor with a summary of what happened after it. The target is a working-set choice, not an age choice: keep raw context only when it will help the next action; summarize or drop raw process when it would distract.
 
-| Category | Pattern | Examples |
-| :--- | :--- | :--- |
-| **Start** | `<task>-start` | `auth-jwt-start`, `docker-setup-start` |
-| **Plan** | `<task>-plan` | `api-v2-plan`, `migration-plan` |
-| **Milestone** | `<task>-<milestone>` | `auth-jwt-impl-done`, `tests-passed` |
-| **Backup** | `<task>-raw-history` | `auth-jwt-raw-history` |
-| **Failure** | `<task>-fail-<reason>` | `auth-jwt-fail-timeout` |
+This prevents both premature cleanup after final answers and endless checkpoint-only behavior that lets stale work accumulate.
 
-**How to generate:** Ask yourself "What is the task?" → Extract 1-3 keywords (e.g., "fix login timeout" → `login-timeout-fix-start`)
+## Main loop
 
-### Squash Noise, Keep Signal, Focus on Goal (Context Hygiene)
-Think of your conversation as a "Feature Branch" full of messy thoughts.
-**You must distinguish Signal from Noise.**
+1. Before noisy work, create a semantic checkpoint as the first context-management action, even if the next visible step is asking for missing inputs. If the first job is orientation over existing history, run `context_timeline` before adding a new checkpoint.
+2. When the task shape is clear, read one matching scenario reference only if it will change tool timing, anchor choice, or summary content. Skip reference loading for obvious short applications where this main skill body is enough. Do not stop after checkpoint-only unless the prompt is intentionally lightweight.
+3. Add checkpoints at meaningful milestones: phase boundaries, risky attempts, reusable batch methods, and interruptions.
+4. Use `context_timeline` when the active path structure affects the next decision or compact target.
+5. At phase boundaries, run the compact gate before starting another phase. If the whole requested task is complete and only the final response remains, answer and wait; let the next user message determine whether cleanup is useful.
+6. After a successful compact, continue from the injected summary instead of dragging the full raw path forward.
 
-*   **Signal (High Value):** Design decisions, user constraints, final working code. -> **KEEP.**
-*   **Noise (Low Value):** Failed attempts, long tool outputs, "thinking" steps. -> **SQUASH.**
-*   **Focus on Goal:** Ask yourself: "Does this message help me achieve the current goal?" -> **KEEP.**
+## Read the right reference
 
-**When to Squash:**
-1.  **Task Done:** Convert the messy process into one clean summary.
-2.  **Low Density:** You read 2000 lines but only found 1 error.
+Read **one primary reference** based on task shape when the scenario pattern will affect tool timing, anchor choice, or summary content:
 
-**Safety:** Squashing is **LOSSLESS**.
-By using `backupTag`, you save the "Messy Branch" forever. You can always checkout the backup tag if the summary isn't enough.
-*   **Main Trunk:** Jump back to the summary.
-*   **Backup Tag:** Jump back to the raw details.
+- search / research / reading-heavy work, especially web search, browser operation, or low-density webpages -> `references/search-research-and-reading.md`
+- development / debugging / troubleshooting / refactoring / migration -> `references/development-and-troubleshooting.md`
+- planning / staged execution / todo-driven work -> `references/planning-and-execution.md`
+- repeated similar items / batch work -> `references/repeated-items-and-batch-work.md`
+- task switching / pause-resume / interruptions to a mainline task / scattered-thread cleanup-and-continue -> `references/task-switching-and-cleanup.md`
 
-### Fail Fast, Revert Faster
-If you fail 3 times:
-1.  **STOP.** Don't try a 4th time.
-2.  `context_checkout` back to the last safe tag.
-3.  Summarize the failure in the checkout message ("Tried X, failed because Y").
-4.  Try a new approach from the clean state.
+Also read `references/retry-branch-and-pivot.md` when multiple approaches, failed branches, comparisons, retries, or pivots become central. For code/debugging work with repeated attempts, use both `references/development-and-troubleshooting.md` and `references/retry-branch-and-pivot.md`.
 
-### After Checkout: Execute Next Step
-
-When `context_checkout` completes and injects a summary, you are in a **new context**.
-
-1. **READ** the injected summary carefully
-2. **EXECUTE** the `Next Step` from the summary - this is your new task.
+## Tool policy
 
-## Decision Matrix: When to Act
-
-| Situation | Action | Reason |
-| :--- | :--- | :--- |
-| **Starting Task** | `context_tag({ name: "<task-slug>-start" })` | Create a rollback point. |
-| **Research / Logs** | `context_checkout` (Squash) | **Process is Noise.** Read 2000 lines -> Keep result. |
-| **Messy Debugging** | **Squash w/ Backup** | **Cleanup.** The error logs are noise once fixed. |
-| **Task Done (Candidate)**| **Squash w/ Backup** | **Assume Success.** Summary is usually enough. Backup exists if not. |
-| **Goal Shift** | `context_checkout` (Squash) | Old context is irrelevant. |
-| **Drift (some steps w/o tag)** | **Tag (Milestone)** | Maintain the skeleton. Don't fly blind. |
-
-## The "Context Health" Check
-
-If you cannot answer these, run `context_log`:
+### `context_checkpoint`
 
-| Question | Answer Source |
-| :--- | :--- |
-| **Where is the skeleton?** | The sequence of `tag`s in the log. |
-| **Is this history useful?** | If "No" -> **SQUASH IT.** |
-| **Am I in a loop?** | Repeated entries in the graph. |
-
-## Good Checkout Messages
-
-The `message` is your lifeline to your past self.
-A good message preserves critical context that would otherwise be lost.
-
-Structure: `[Key Finding/Status] + [Reason] + [Important Changes] + [Next Step]`
-
-*   **Key Finding/Status**: What did you discover or complete? Include specific numbers, errors, or outcomes.
-*   **Reason**: Why are you branching/moving? (e.g., "Task complete", "Approach failed", "Need raw logs")
-*   **Important Changes**: What files or logic have been modified? (This checkout only resets *conversation history*, NOT disk files, so you must remember what changed.)
-*   **Next Step**: What should you do immediately after this squash? Be specific. (e.g., "Wait for user feedback", "Implement the recommended fix", "Revert file X and try approach Y")
-
-Examples:
-
-*   *Good (Resetting after failure)*: "Recursive parser hit stack overflow at depth 8000. Switching to iterative. **Reason**: Stack limit reached. **Important Changes**: Modified `utils/recursion.ts`. **Next Step**: Inform user of the failure and propose iterative approach."
-*   *Good (Cleaning up)*: "Auth module complete: JWT + OAuth2 + RBAC. 23 tests passing. **Reason**: Task done, cleaning context. **Important Changes**: Created `auth/`, modified `routes.ts` and `middleware.ts`. **Next Step**: Report completion to user, ask if they want to review or test."
-*   *Bad*: "Switching context." (Too vague - you will forget why)
-*   *Bad*: "Done." (What is done? What should you do next?)
-
-## Anti-Patterns
-
-| Don't | Do Instead |
-| :--- | :--- |
-| **Blind Tagging** (Tagging without looking) | **Check** (`context_log`) to avoid duplicates or tagging noise. |
-| **Over-Tagging** (Tagging every step) | **Tag** only major phase changes (`start`, `milestone`). |
-| **Hoard** (Keep all history "just in case") | **Squash** low-density history (research, logs). |
-| **Panic** (Apologize repeatedly for errors) | **Revert** (`context_checkout`) to before the error. |
-| **Blind Checkout** (Guessing IDs) | **Look** (`context_log`) first to get valid IDs. |
-| **Vague Summaries** ("Done", "Fixed") | **Detailed Summaries** ("Found bug in line 40. Fixed with patch X.") |
-| **Generic Tag Names** (`task-start`, `phase-1`) | **Semantic Names** (`auth-jwt-start`, `db-schema-plan`) |
-| **Missing Next Step** in checkout message | **Always specify** what to do after squash (e.g., "Wait for user", "Implement fix X") |
-
-## Recipes (Copy-Paste)
-
-### 1. The "Miner" (Immediate Squash)
-**Goal:** Pure information gathering (Reading files, Searching web).
-**Why:** The *process* of searching is irrelevant. Only the *result* matters.
-
-**Example Task:** Analyzing error logs to find root cause of timeout
-
-```javascript
-// 1. Tag BEFORE starting the noisy work (use descriptive name)
-context_tag({ name: "timeout-analysis-start" });
-
-// ... (Read 5 log files, search 3 docs, find DB connection pool exhaustion) ...
-
-// 2. Squash IMMEDIATELY. Do not wait for user.
-context_checkout({
-  target: "timeout-analysis-start",
-  message: "Found DB connection pool exhaustion as root cause (pool size: 10, peak load: 1000 req/s). Recommended fix: increase to 50. **Reason**: Context cleanup after research. **Important Changes**: None (read-only). **Next Step**: Report findings to user and await approval to implement fix.",
-  backupTag: "timeout-analysis-raw-history" // Safety backup
-});
-context_tag({ name: "timeout-analysis-done" });
-```
-
-### 2. The "Candidate" (Wait for Confirmation)
-**Goal:** You finished a complex task.
-**Why:** The history is noisy. The result is clean.
-**Safety:** We create a backup tag automatically.
-
-**Example Task:** Implementing OAuth login flow
-
-```javascript
-// Squash to Summary (Optimistic Cleanup)
-context_checkout({
-  target: "oauth-impl-start", // Squash range: Start -> Now
-  message: "OAuth2 flow implemented with PKCE, Google + GitHub providers. All 12 tests passing. **Reason**: Task complete, cleaning up. **Important Changes**: Created `auth/oauth.ts`, modified `routes.ts`, `config.ts`. **Next Step**: Report completion to user, summarize what was implemented.",
-  backupTag: "oauth-impl-raw-history"
-});
-context_tag({ name: "oauth-impl-candidate" });
-```
-
-### 3. The "Undo" (Revert Squash)
-**Goal:** User asks about a detail you squashed away.
-**Action:** Jump back to the backup tag.
-
-**Example Task:** Reviewing OAuth implementation details
-
-```javascript
-// Jump back to the raw history
-context_checkout({
-  target: "oauth-impl-raw-history",
-  message: "Reviewing token refresh logic - user reports 401 after 15 min idle. Suspect refresh token not firing. **Reason**: Need raw logs to trace the bug. **Important Changes**: None. **Next Step**: Re-read token refresh implementation and identify the bug."
-});
-context_tag({ name: "oauth-review-start" });
-```
-
-### 4. Branching (Alternative Approach)
-**Scenario:** Method A failed (and was squashed). You want to try Method B from the clean state.
-**Action:** Checkout the start point.
-
-**Example Task:** Fixing memory leak - trying different approaches
-
-```javascript
-// Method A (weak references) failed, trying Method B (object pooling)
-context_checkout({
-  target: "memory-leak-fix-start", 
-  message: "WeakRef approach failed: objects GC'd within 30s (expected: 5min). Cache hit rate dropped from 95% to 12%. **Reason**: Switching to object pooling approach. **Important Changes**: `CacheManager.ts` modified (will revert). **Next Step**: Revert `CacheManager.ts` changes and implement object pooling strategy."
-});
-context_tag({ name: "memory-leak-pool-approach-start" });
-```
-
-### 5. The "Undo" (Failed Attempt)
-You tried to fix a bug but broke everything.
-**Goal:** Clean up a failed path.
-
-**Example Task:** Fixing race condition in async handler
-
-```javascript
-// Attempted mutex-based fix, but introduced deadlock
-context_checkout({
-  target: "race-condition-fix-start",
-  message: "Mutex caused deadlock: Thread A holds mutex, awaits callback; callback needs mutex held by B; B waits for A. Circular wait detected. **Reason**: Trying lock-free CAS approach next. **Important Changes**: `AsyncQueue.ts` lines 70-90 modified (backup saved). **Next Step**: Revert `AsyncQueue.ts` and implement lock-free compare-and-swap approach.",
-  backupTag: "race-condition-mutex-fail" // Save the failure for reference
-});
-context_tag({ name: "race-condition-lockfree-start" });
-```
+Default move. Use it before noisy work, a new phase, a risky attempt, switching subtasks, or after a meaningful milestone.
+
+Use semantic names so the timeline stays readable:
+
+- `<task>-start`
+- `<task>-<phase>`
+- `<task>-<attempt>`
+- `<task>-<milestone>`
+
+Examples: `auth-oauth-start`, `timeout-analysis-search`, `db-migration-plan`, `parser-fix-attempt-2`.
+
+Avoid generic names like `start`, `checkpoint-1`, `phase-1`, or `retry`.
+
+### `context_timeline`
+
+Use it as the structural view of the active path, not only as a rescue tool:
+
+- when the current path shape affects the next decision
+- when several checkpoints, branches, or task switches exist
+- before choosing a compact target that is not obvious
+- when the thread feels cluttered and you need to distinguish useful context from baggage
+
+When reading the timeline, ask:
+
+- What is the current task and immediate next action?
+- Which prior raw messages are still needed for that next action?
+- Which completed, failed, or unrelated paths are now baggage?
+- Which anchor gives the smallest sufficient working set after summary injection?
+
+### `context_compact`
+
+Use it to replace raw history with a state summary when the next phase would benefit from a smaller working set.
+
+Typical compact boundaries: investigation -> execution, diagnosis -> fix, implementation -> validation, failed attempt -> next attempt, representative item -> remaining batch, completed noisy task -> new user task.
+
+Do not compact while exploration is still active, when the result is unstable, just because the skill triggered, or just because the user-visible task ended.
+
+## Compact gate
+
+Before calling `context_compact`, require all three:
+
+1. The segment being left behind is noisy, stale, failed, low-value in raw form, or actively reducing focus.
+2. You can restore the useful task state in a clear summary.
+3. There is an immediate continuation that benefits from cleaner context.
+
+If the compact is prompted by a new user message, a direction shift, or several possible checkpoint targets, run `context_timeline` first and choose the target from the visible structure rather than from memory.
+
+Condition 3 means the next action is a new phase, not just more of the same exploration. Examples: run the export, implement the fix, validate, process the next item, or try the chosen next approach.
+
+If conditions 1 and 2 are true but the whole task is done and only the final answer remains, wait. Compact later only if the next user message makes it useful.
+
+## Choosing target and backup
+
+Choose the continuation anchor by designing the next working set:
+
+1. Name the immediate next action.
+2. Decide what must remain raw: active user intent, current constraints, still-open evidence or code context, an approved plan being executed, or details you expect to inspect directly next.
+3. Decide what can become state summary or disappear: completed searches, verbose logs, failed attempts, stale branches, earlier unrelated tasks, and process details whose useful value is already clear.
+4. Pick the anchor that leaves the new branch with the **smallest sufficient context** after summary injection.
+5. If an older anchor plus a stronger summary is cleaner than a recent anchor plus stale context, prefer the older anchor.
+
+The right target may be a recent phase-start, a plan-ready checkpoint, a pre-branch checkpoint, a repeated-work baseline, an older checkpoint, or `root`. `root` is appropriate when the old path no longer contributes raw context and the summary can carry the necessary state.
+
+Avoid targets that create a poor working set:
+
+- too late: the new branch still contains the clutter, failed path, or unrelated task you meant to leave behind
+- too early with a weak summary: the next phase loses constraints, decisions, evidence, or changed-file state it needs
+- semantically wrong: the anchor preserves a context frame that no longer matches the current task
+
+For bounded phases, choose by what should remain raw:
+
+- target `research-start` to summarize the whole research segment
+- target `research-end` to keep research raw and summarize only later clutter before follow-up research
+
+If there are several checkpoints, a task switch, or any uncertainty about the best working set, run `context_timeline` first.
+
+Use `backupCheckpoint` when the raw path may still matter later: long investigations, abandoned branches, risky compactions, or details that may be needed for recovery. A backup checkpoint is a recovery safety net, not a substitute for the summary; include details likely needed in the next phase because returning to backup is costly.
+
+## Compact summary contract
+
+The summary is not a transcript recap. It is the state needed to resume work from the chosen anchor; older or cleaner anchors require stronger summaries.
+
+Context tools change conversation state, not the outside world. Files, processes, browser state, tickets, databases, remote services, and other side effects stay current. If you compact to an anchor before those changes, the summary must bridge the gap between old conversation context and current external state.
+
+A compact summary must restore:
+
+1. **Task state:** current task, user intent, constraints, decisions, assumptions, and known result/progress/failure.
+2. **External state:** changed files, created/deleted artifacts, running/stopped processes, browser actions, tickets/records, deployments, remote changes.
+3. **Verification state:** commands already run, validation status, notable outputs, and remaining risks or open questions.
+4. **Navigation state:** source anchors/evidence when needed, rejected leads worth avoiding, backup checkpoint guidance, and the explicit next step.
+
+Include why compacting is appropriate only when it helps future orientation. Avoid vague summaries like `Done`, `Investigated`, `Switching context`, or `Going back`.
+
+Good examples:
+
+- `Current task: plan mitigation for API timeouts. State: DB pool exhaustion is the likely root cause. Evidence: logs show pool wait timeouts during peak traffic; config has pool size 10; no network errors found. Rejected lead: API gateway timeout appears downstream of DB waits. Next step: propose mitigation and validation steps.`
+- `Current task: validate the parser fix. State: implementation is done. External state: changed files src/parser.ts and test/parser.test.ts. Validation not yet run after the final edit. Next step: run targeted parser tests and summarize remaining edge cases. Backup: parser-fix-debug-history if exact failed attempts are needed.`
+
+Before compacting, quickly check: stable state? real continuation? anchor gives the smallest sufficient working set? summary restores state after that anchor? external side effects and validation captured? explicit next step?
+
+## After compact
+
+1. Read the injected summary carefully.
+2. Treat it as the new active state.
+3. Before continuing, verify it contains enough state for the next action.
+4. Remember that disk and external systems were not rolled back by the context move; if state matters, inspect the current files/tools/services rather than trusting the historical anchor.
+5. If a missing detail is cheap to reconstruct from disk, tools, or source anchors, retrieve it directly.
+6. Return to the backup checkpoint only when the missing raw context cannot be reconstructed cheaply.
+
+## Common mistakes
+
+Avoid:
+
+- checkpointing constantly without phase meaning
+- compacting blindly without timeline when anchor choice is unclear
+- preserving too much raw history because older anchors or `root` feel risky
+- using an old anchor or `root` with a weak summary that drops current task state
+- compacting immediately after a final deliverable when no next user intent is known
+- carrying completed noisy phases into a new task
+- writing summaries that recap history but fail to restore current task state
+- assuming compact or branch navigation reverts files, processes, browser state, or remote services
+- omitting decisions, constraints, external side effects, changed files, validation status, or next step