pi-context 2.0.0-beta.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Pi Context: Agentic Context Management for Pi
 
-An Agentic Context Management tool that helps AI agents proactively manage checkpoints, timeline inspection, and rewind-based context cleanup.
+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, it brings lossless time travel to Pi's session tree.
 
@@ -13,9 +13,9 @@ Earlier versions used more Git-like names such as `context_tag`, `context_log`,
 Current versions intentionally use conversation-native names instead:
 - `context_checkpoint`
 - `context_timeline`
-- `context_rewind`
+- `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`.
+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
 
@@ -43,13 +43,13 @@ Open a visual dashboard to inspect context-window usage and token distribution (
 
 ### For Agents
 
-This extension adds the `context-management` skill, which includes 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_checkpoint`)**
-   Create named checkpoints to organize 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_timeline`)**
-   Visualize conversation history, inspect 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_rewind`)**
-   Return to an earlier checkpoint or anchor with a carryover summary so completed noisy work can be compacted into a cleaner continuation.
+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,6 +1,6 @@
 {
   "name": "pi-context",
-  "version": "2.0.0-beta.0",
+  "version": "2.1.0",
   "description": "Agentic Context Management for Pi",
   "files": [
     "src",
@@ -15,18 +15,19 @@
     "pi-package",
     "context-management",
     "context-optimization",
+    "context-compact",
     "time-travel",
     "checkpoint",
     "pi-skill"
   ],
   "type": "module",
-  "author": "",
+  "author": "ttttmr",
   "license": "MIT",
   "devDependencies": {
-    "@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"
+    "@earendil-works/pi-ai": "^0.80.6",
+    "@earendil-works/pi-coding-agent": "^0.80.6",
+    "@earendil-works/pi-tui": "^0.80.6",
+    "typescript": "^5.9.3"
   },
   "pi": {
     "extensions": [

package/skills/context-management/SKILL.md

@@ -1,274 +1,205 @@
 ---
 name: context-management
-description: Read this skill for work that is likely to stretch across many turns or get messy if handled in one uninterrupted thread. Especially use it when the request sounds like first go search or read a lot, first look through logs/files/pages/results and come back with the real conclusion, this will probably take several rounds, there may be several approaches to try, first make a plan or todo list and then work through it, there will be many similar cases to handle, the user may interrupt with side tasks, or the thread is already getting messy and should be cleaned up before continuing. It teaches a working mode built around frequent checkpoints, periodic timeline review, and targeted rewinds as the task evolves. Usually skip it for one-shot reads, bounded summaries, direct rewrites, or deterministic scripts.
+description: "Use this skill for multi-turn, phased, or noisy work: research/reading, debugging, plan-then-execute, retries/pivots, background or asynchronous work, handoffs, user decisions, task switching, repeated items, or repeated progress checks. It keeps the conversation as a clean working set with checkpoints, timeline review, and compaction at continuation boundaries. Always use when resuming after context compaction or when a long phase reaches a decision, handoff, validation, or task-switch boundary. Usually skip simple one-shot tasks."
 ---
 
 # Context Management
 
-Use this skill to adopt an explicit conversation-management working mode.
+Use this skill to keep the active conversation as a useful **working set** for the next step. Keep raw only the context that still needs direct reasoning; carry the rest as compact task state when that is more efficient.
 
-This mode is for tasks where the work may still be valid, but the thread carrying it is likely to become long, noisy, multi-phase, or hard to keep clean. The goal is to keep the work navigable: checkpoint early, review timeline when needed, and compact completed noisy phases back to clean anchors.
+Core rhythm:
+
+- **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**
+
+Use only these tools:
 
-Use only the current tool names:
 - `context_checkpoint`
 - `context_timeline`
-- `context_rewind`
+- `context_compact`
+
+## Working-set model
+
+Before choosing a tool, ask:
 
-## When to use this skill
+- What am I trying to do next?
+- What facts, constraints, or artifacts must stay raw for that next action?
+- What important data has a reliable external source I can re-check instead of carrying raw?
+- What history is useful only as a conclusion, pointer, or state update?
+- What history is process noise or stale baggage?
 
-Read this skill when the task is likely to outgrow one clean thread and would benefit from explicit history management.
+Classify context into:
 
-It should feel like a good fit when the user is effectively asking for one of these patterns:
+- **Raw context:** user intent, constraints, code/log/error details, evidence, or plan text you expect to inspect directly soon.
+- **State summary:** decisions, findings, lessons, changed files, validation status, source pointers, 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 gone.
 
-### “First go look through a lot of stuff, then come back with the real conclusion.”
-Examples:
-- searching or researching first
-- web search or browser-driven information gathering
-- reading many files, logs, docs, webpages, or web results
-- review / comparison / audit-heavy reading across many sources
+If the active context is already small, coherent, and directly useful for the next step, do not manage it just to be tidy.
 
-### “This will probably take several rounds or several phases.”
-Examples:
+## When to use
+
+Use this mode when the work may outgrow one clean thread:
+
+- search, research, browser work, or reading many files/logs/pages/results
 - investigate -> decide -> execute -> validate
 - plan -> implement -> verify
-- collect -> compare -> conclude
-- any task that will keep changing shape as it progresses
-
-### “We may need to try more than one route.”
-Examples:
-- A / B / C approaches
-- dead ends and retries
-- compare and choose
-- pivoting after a failed direction
-
-### “Start from a plan or todo list, then work through it.”
-Examples:
-- a formal implementation or migration plan
-- a roadmap with milestones
-- a lightweight todo list or checklist
-- staged execution that will be revisited across many turns
-
-### “There will be many similar cases, tickets, or items.”
-Examples:
-- repeated cases
-- repeated tickets
-- repeated checks
-- repeated reviews
-- repeated fix attempts on similar inputs
-
-### “I may interrupt you, or this thread is already getting messy.”
-Examples:
-- the user may insert side tasks
-- you need to pause one line of work and resume it later
-- the thread is already long, stale, or cluttered
-- finished noisy phases should be cleaned up before continuing
-
-### “This is code-facing work and may turn noisy while I debug or implement it.”
-Examples:
-- implementation
-- debugging
-- troubleshooting
-- refactoring
-- migration
-- code-facing review or fix work
-
-If one of these patterns clearly applies, take the first structural action now—usually a checkpoint—instead of only describing the intended workflow.
-
-If multiple approaches, failed branches, compare work, or pivots become central, also read `references/retry-branch-and-pivot.md` in addition to the main scenario reference.
-
-## When to skip it
-
-Usually skip this skill for:
-- one-shot reads
-- bounded summaries
-- direct rewrites with little exploration
-- simple fact lookup or concept explanation
-- deterministic scripts or fixed-rule automation
-- short tasks that can stay clean in one thread
-
-## Operating rhythm
-
-1. Before entering a noisy phase, create a checkpoint.
-2. If you feel disoriented or anchor choice is unclear, run `context_timeline`.
-3. Add more checkpoints at milestones, phase boundaries, risky branches, and interruptions.
-4. Do not rewind just because the skill triggered.
-5. Once a noisy phase is complete and summarizable, rewind to the best earlier clean anchor.
-6. Continue from the compacted state instead of dragging the full messy path forward.
-
-The key habit is: **checkpoint is the default move; rewind is the selective cleanup move.** Checkpointing alone is not the end state. Checkpoints create anchors so that completed noisy phases can later be compacted cleanly.
+- background or asynchronous work, handoffs, user decisions, or delayed results
+- multiple approaches, retries, failed branches, comparisons, or pivots
+- repeated similar cases, tickets, reviews, or batch items
+- a main task that may be interrupted by side tasks
+- repeated progress/status checks that indicate active state is hard to track
+- scattered threads that need cleanup before continuing
+- debugging, troubleshooting, refactoring, migration, or code-facing work that may get noisy
 
-## Tool policy
+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 provided enough task details, still checkpoint the workflow shape before asking clarifying questions.
 
-### `context_checkpoint`
-This is the default tool in this mode.
+Usually skip this skill for one-shot reads, bounded summaries, direct rewrites, simple lookups, deterministic scripts, short tasks that can stay clean, or moments where the active context is already a good working set.
 
-Use it:
-- before noisy work
-- before a new phase
-- after a meaningful milestone
-- before a risky attempt
-- before switching to another subtask
+## Start-of-turn check
 
-Use semantic names so the timeline stays readable.
+At the start of each new user message, classify it:
 
-Recommended patterns:
-- `<task>-start`
-- `<task>-<phase>`
-- `<task>-<attempt>`
-- `<task>-<milestone>`
+- **Same task / next phase:** continue; if the previous phase is complete and noisy, compact before the next phase.
+- **Correction or follow-up:** usually answer from recent context; do not compact yet.
+- **New task or direction shift:** if the previous task left a complete noisy segment, inspect timeline when anchors are unclear, then compact to a continuation anchor that gives the new task a clean working set.
 
-Examples:
-- `auth-oauth-start`
-- `timeout-analysis-search`
-- `db-migration-plan`
-- `parser-fix-attempt-2`
-- `vendor-review-milestone-1`
+Think of the tools as a phase pipeline: checkpoint marks anchors, work happens, timeline shows structure, and 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.
 
-Avoid generic names like `start`, `checkpoint-1`, `phase-1`, or `retry`.
+## Main loop
 
-### `context_timeline`
-Use this tool to regain orientation.
-
-Use it:
-- when you feel lost or drifted
-- when several checkpoints or branches now exist
-- before choosing a rewind target
-- at major phase transitions if you need a quick map
-- when the thread feels cluttered and you want a structural view before acting
-
-When you inspect timeline, ask:
-- Where is the nearest clean anchor?
-- Has the current segment grown too long without a clean checkpoint?
-- Am I carrying a failed or stale branch forward?
-- Is there already a better checkpoint to rewind to?
-
-### `context_rewind`
-Use this tool to compact a path that should no longer stay active in full.
-
-Use it:
-- after a noisy investigation has produced a stable finding
-- after a failed attempt has produced a clear lesson
-- after a completed phase where the next step is clear
-- after a representative item or branch has already taught you what you need
-- when the current path is dragging too much stale or low-value context forward
-
-A successful use of this mode often ends with `context_rewind`, not just more checkpointing.
-
-## Rewind protocol
-
-### When to rewind
-Rewind when the current phase is ready to be compacted.
-
-Good reasons to rewind:
-- a phase produced a stable finding or conclusion
-- a failed path produced a clear dead-end lesson
-- a milestone was reached and you want a cleaner continuation
-- a representative item or branch has already taught you the reusable lesson
-- the thread is carrying more stale intermediate process than active value
-
-A phase is usually rewind-ready when you now have one of these:
-- a root cause or research conclusion
-- a clear failure reason for abandoning a branch
-- a completed implementation or troubleshooting phase
-- a reusable method learned from a representative item
-- a finished repeated-item segment whose raw path no longer needs to stay live
-
-Do **not** rewind yet when:
-- you are still in the middle of active exploration
-- the result is still unstable or incomplete
-- you only feel mild clutter and a checkpoint would be enough
-- you have not yet decided which earlier anchor you want to continue from
-
-When in doubt: checkpoint first, review timeline if needed, and rewind later once the phase boundary is clearer.
-
-### Choose the target and backup
-Choose the **best earlier clean anchor**, not just any earlier checkpoint.
-
-Usually prefer:
-- the start of the noisy phase you are compacting
-- the nearest clean phase-start before the current failed or completed path
-- the repeated-work anchor for repeated-item workflows
-- the last stable pre-branch checkpoint when abandoning an approach
+1. Before noisy work, create a semantic checkpoint as the first context-management action. 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.
+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 continuation 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.
+6. After a successful compact, continue from the injected summary instead of dragging the full raw path forward.
 
-Avoid:
-- rewinding too far back when a nearer clean anchor exists
-- rewinding to a checkpoint that still includes the noise you want to leave behind
-- defaulting to `root` unless the whole active path should be reset
-
-If you are unsure which anchor is best, run `context_timeline` first.
-
-Use `backupCheckpoint` when:
-- the raw path may still be useful later
-- you are compacting a long investigation
-- you are abandoning a branch but may need its details again
-- you want a safe recovery point before a major rewind
-
-A backup checkpoint preserves the raw path you are compacting. If the summary later proves insufficient, return to that backup instead of redoing the whole investigation.
-
-If the raw path is low value and unlikely to matter again, a backup is optional.
-
-### Write the message
-A rewind message is the baton pass to future-you. It is not a throwaway comment.
-
-At minimum, include:
-- the main result, lesson, or failure summary
-- why you are rewinding now
-- important changes, especially changed files if disk state changed
-- the next step after the rewind
-
-Useful shapes:
-- `[result] + [reason for rewind] + [next step]`
-- `[result] + [reason for rewind] + [important decision or change] + [next step]`
-- `[result] + [reason for rewind] + [important changes / changed files] + [next step]`
-
-Good examples:
-- `Found DB connection pool exhaustion as the likely root cause. Reason: investigation phase is complete and ready to compact. Next step: report findings and propose mitigation.`
-- `Parser fix is implemented and the debugging phase is complete. Reason: compacting implementation history before focused validation. Important changes: modified src/parser.ts and test/parser.test.ts. Next step: run targeted validation and summarize remaining edge cases.`
-- `WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Reason: abandoning this attempt and returning to a clean anchor. Next step: try object pooling instead.`
-
-Avoid vague messages like:
-- `Done`
-- `Switching context`
-- `Investigated`
-- `Going back`
-
-Before using `context_rewind`, quickly check:
-- Is there already a stable result, lesson, or failure summary?
-- Do I know why this is the right moment to rewind?
-- If disk state changed, did I record the important changes or changed files?
-- Is the next step explicit?
-- Would future-me understand what changed just from this message?
-
-If not, keep working a bit longer or checkpoint first.
-
-### After rewind
-When `context_rewind` succeeds:
-1. Read the injected summary carefully.
-2. Treat it as the new active state.
-3. Execute the next step from that summary.
-4. Do not keep reasoning from the full old path unless you intentionally return to a backup checkpoint.
+## Continuation boundaries
 
-## Common mistakes
+A continuation boundary is a point where the current phase has produced a stable result and the next action will use that result to start a different phase. It is not necessarily the end of the user's whole task.
 
-Avoid:
-- checkpointing constantly without phase meaning
-- rewinding blindly without checking timeline when anchor choice is unclear
-- carrying completed noisy phases forward instead of compacting them
-- writing vague rewind messages that future-you cannot act on
+Examples: investigation -> decision/plan/implementation, implementation -> validation, failed validation -> next approach, delayed result -> routing/action, user decision -> execution, rejected branch -> replacement direction, side request -> pause/summarize mainline before switching.
+
+Do not ask only "is the whole task done?" Ask "will the next action start a new phase using the stable result of this phase?" If yes, this is often a compaction boundary.
+
+Handoffs are not final answers: if a response transfers control to the user, another actor/process, later validation, or a queued phase, compact when the prior phase was noisy and the next action needs only stable state.
 
 ## Read the right reference
 
-Read **one primary reference** based on the task shape:
-- search / research / reading-heavy work, especially web search, browser operation, or low-density webpage reading -> `references/search-research-and-reading.md`
+Read **one primary reference** only when the scenario pattern will affect tool timing, anchor choice, or summary content:
+
+- search / research / reading-heavy work -> `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 / cleanup-and-continue work -> `references/task-switching-and-cleanup.md`
+- task switching / pause-resume / interruptions / cleanup-and-continue -> `references/task-switching-and-cleanup.md`
+- interleaved async work / overlapping fronts / background results / user decisions -> `references/interleaved-async-work.md`
+
+Also read `references/retry-branch-and-pivot.md` when multiple approaches, failed branches, comparisons, retries, or pivots become central.
+
+## Tool policy
+
+### `context_checkpoint`
+
+Use before noisy work, a new phase, a risky attempt, switching subtasks, or after a meaningful milestone. Use semantic names such as `<task>-start`, `<task>-<phase>`, `<task>-<attempt>`, or `<task>-<milestone>`. Avoid generic names like `start`, `checkpoint-1`, or `retry`.
+
+### `context_timeline`
+
+Use it as the structural view of the active path:
+
+- when the current path shape affects the next decision
+- when several checkpoints, branches, or task switches exist
+- before choosing a non-obvious compact target
+- when the thread feels cluttered and you need to distinguish useful context from baggage
+
+When reading the timeline, ask which raw messages are still needed for the immediate next action, which paths are now baggage, and 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.
 
-Then read the cross-cutting retry reference when needed:
-- multiple approaches, failed branches, compare, retry, or pivot behavior -> `references/retry-branch-and-pivot.md`
+Typical compact boundaries: investigation -> execution, diagnosis -> fix, implementation -> validation, failed attempt -> next attempt, representative item -> remaining batch, completed noisy task -> new user task.
 
-Keep the mode simple:
-- checkpoint before mess
-- review timeline when orientation matters
-- rewind when a phase is ready to be compacted
+Strong signals to consider compaction:
+
+- repeated progress/status checks
+- inability to summarize current state, next action, and open risks in one short paragraph
+- rejected, abandoned, or superseded branches
+- stable result after many tool calls or long output
+- returned background/asynchronous/delegated result
+- material plan or approach change
+- side question arriving while stale process history is active
+
+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 visible structure rather than memory.
+
+If the whole task is done and only the final answer remains, wait. Compact later only if the next user message makes it useful.
+
+Checkpoint-only failure mode: a checkpoint is useful because it gives you a clean anchor to compact back to later. After any checkpointed phase produces a stable result, ask what the phase settled, whether the next step is different, and whether a summary can replace the raw trail. If yes, compact; do not keep accumulating raw history just because the overall task is still active.
+
+## 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/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, externally recoverable data, and clear process details.
+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. When completed fronts fill the middle of the thread, it can be correct to compact to a much older anchor or even `root` if the summary restores the active front and source pointers.
+
+Avoid targets that are too late, too early with a weak summary, or semantically wrong. If there are several checkpoints, a task switch, or uncertainty about the best working set, run `context_timeline` first.
+
+Use `backupCheckpoint` when raw history may still matter later. A backup is a recovery safety net, not a substitute for the summary.
+
+## 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 explicit next step.
+
+If important data has a reliable external source, preserve the pointer and retrieval method rather than copying the raw data. Examples: file path and line/query, database table/query, task/job id, log path, URL, record id, branch/commit, or command to inspect status. Include raw values only when they are small, unstable, hard to retrieve, or needed for immediate reasoning.
+
+For long-running work, shape the summary as a state capsule: goal, stable result, decisions, rejected paths, current artifacts/source pointers, active work, pending input, risks/open questions, and next action. Include why compacting is appropriate only when it helps future orientation. Avoid vague summaries like `Done`, `Investigated`, `Switching context`, or `Going back`.
+
+Before compacting, quickly check: stable state? real continuation? smallest sufficient working set? summary restores state after the anchor? externally recoverable data represented by pointers? external side effects and validation captured? explicit next step?
+
+## After compact
+
+1. Read the injected summary carefully and treat it as the new active state.
+2. Verify it contains enough state for the next action.
+3. Remember that disk and external systems were not rolled back; inspect current files/tools/services when state matters.
+4. If a missing detail is cheap to reconstruct from disk, tools, or source anchors, retrieve it directly.
+5. Return to the backup checkpoint only when the missing raw context cannot be reconstructed cheaply.
+
+## Common mistakes
+
+Avoid:
+
+- checkpointing constantly without phase meaning
+- checkpointing early but never compacting after a stable phase result
+- 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
+- compacting immediately after a final deliverable when no next user intent is known
+- carrying completed noisy phases into a new task
+- treating handoff or decision prompts as final answers when a continuation is expected
+- 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

package/skills/context-management/references/development-and-troubleshooting.md

@@ -15,7 +15,7 @@ These tasks often stay cleaner when treated as stages with anchors, instead of o
 1. Create a checkpoint before starting serious work.
 2. Add checkpoints before risky edits, new approaches, or major phase changes.
 3. Review the timeline when you need to understand the current shape of the work.
-4. Rewind after a stable implementation milestone, a failed approach, or a completed troubleshooting phase.
+4. Compact after a stable implementation milestone, a failed approach, or a completed troubleshooting phase when there is another phase, attempt, validation step, or task switch that benefits from cleanup. If files, processes, or external systems changed, include those side effects in the summary because context navigation does not roll them back. If the completed phase is also the final user-visible deliverable, answer first and wait.
 
 ## Typical checkpoint moments
 
@@ -40,28 +40,28 @@ Run `context_timeline` when:
 - you are about to abandon one approach and restart from another anchor
 - you are unsure which checkpoint best represents the clean continuation point
 
-## Rewind patterns
+## Compact patterns
 
 ### After a failed attempt
 
-Use rewind when an attempt clearly failed and you have a crisp summary of why.
+Use compact when an attempt clearly failed and you have a crisp summary of why.
 
 ```javascript
-context_rewind({
+context_compact({
   target: "memory-leak-fix-start",
-  message: "WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Reason: abandoning this attempt and returning to a clean anchor. Next step: try object pooling instead.",
+  summary: "Current task: continue the memory leak fix. State: WeakRef approach failed because objects were collected too early and cache hit rate collapsed. Decision: abandon WeakRef and try object pooling. Next step: implement the object-pooling approach.",
   backupCheckpoint: "memory-leak-weakref-raw-history"
 });
 ```
 
 ### After a completed phase
 
-Use rewind when a phase is done and you want to continue from a cleaner thread.
+Use compact when a phase is done and the next phase would work better from a focused state summary than from the raw implementation/debugging trail. Do not use this as a reflexive final step after delivering the finished work; use it before validation, the next phase, the next attempt, or the next user task.
 
 ```javascript
-context_rewind({
+context_compact({
   target: "parser-fix-start",
-  message: "Parser fix is implemented and the debugging phase is complete. Reason: compacting implementation history before focused validation. Next step: run targeted validation and summarize remaining edge cases.",
+  summary: "Current task: validate the parser fix. State: implementation is done and the debugging trail can be summarized. External state: parser implementation and related tests were changed on disk; context navigation did not revert them. Validation not yet run after final edit. Next step: run targeted validation and summarize remaining edge cases.",
   backupCheckpoint: "parser-fix-debug-history"
 });
 ```