[Grok] Teach ACM working-set judgment instead of ritual transitions

skills/context-management/CORE.md

@@ -7,9 +7,9 @@ This file is the editable source for always-on ACM guidance and generated tool/r
 
 A context window is a **working set**: the exact material needed for the next action. Keep that detail live. Compress finished process into a recoverable **handoff** only at a named **boundary**.
 
-### ACM preflight
+### Working-set invariant
 
-A distinct user goal begins with an **ACM preflight** on the branch that will carry it. First complete any required `New request arrives over finished work` transition; then call `acm_checkpoint` with a semantic `<chain>-start` name before managed work. When no finished-chain transition is required, the checkpoint call is the first action. Managed work includes investigation, planning, delegation, any non-ACM tool call, file or external side effects, and multi-step reasoning. The preflight is complete only when the tool result confirms that the checkpoint was created or reused. If the call fails, follow the recovery guidance in its result before proceeding. A text-only direct reply requiring no managed work stays outside the managed-chain workflow.
+Conserve the working set: live context holds only what NEXT will reason over. Everything else is still needed live, or already folded into an executable handoff whose **archive** remains recoverable. Tools enforce structure; you judge when a transition earns its place against this invariant.
 
 ### Vocabulary
 
@@ -23,9 +23,15 @@ A distinct user goal begins with an **ACM preflight** on the branch that will ca
 - **rebase** — move all surviving state into one authoritative snapshot at the earliest safe base, retiring accumulated summary depth.
 - **cold start** — a fresh agent can execute `NEXT` from the snapshot and its pointers without archived summaries.
 
-### Normal state transitions
+### ACM preflight
+
+Recoverability has a cost curve: once managed work expands the trail, rewind without an anchor is expensive. A distinct user goal therefore begins with an **ACM preflight** on the branch that will carry it. After any needed `New request arrives over finished work` transition, call `acm_checkpoint` with a semantic `<chain>-start` name before managed work—investigation, planning, delegation, any non-ACM tool call, file or external side effects, or multi-step reasoning. The preflight is complete only when the tool result confirms that the checkpoint was created or reused. If the call fails, follow the recovery guidance in its result before proceeding. A text-only direct reply requiring no managed work stays outside.
+
+### Judgment triggers
 
-| Event | Required transition |
+When one of these situations arises, ask whether the working-set invariant still holds; restore it with the lightest transition that does:
+
+| Situation | Judgment |
 |---|---|
 | Phase, attempt, or batch item starts | checkpoint its `-start` boundary before acting |
 | Unbounded burst or risky step is next | checkpoint before output or side effects arrive |
@@ -35,35 +41,35 @@ A distinct user goal begins with an **ACM preflight** on the branch that will ca
 | New request arrives over finished work | run a rebase check before starting the new chain; if it is not ready, fold the finished local chain |
 | Another fold would stack on an active summary, a stable subchain closes, or context pressure rises | run a rebase check before choosing a local fold or accepting native compaction |
 
-Context pressure triggers a rebase check. It does not lower the cold start gate or authorize travel by itself.
+Context pressure raises priority of a **rebase check**. Cold start remains hard; pressure alone does not authorize travel.
 
-### Fold gate
+### Fold criteria
 
-Travel only when all three criteria hold:
+Travel when all three criteria hold:
 
 1. **Boundary named** — say exactly what raw process leaves the working set.
 2. **NEXT executable** — write one immediate action that can run from the handoff.
 3. **Raw recoverable** — preserve omitted detail through a checkpoint, node ID, file, command, URL, commit, or other pointer.
 
-Call `acm_travel` alone in its assistant tool batch; do not combine this context mutation with sibling tool calls.
+Call `acm_travel` alone in its assistant tool batch; mixed batches are rejected before mutation.
 
-Boundary decides whether folding is valid. Timeline reports evidence; it does not decide for you. A target must sit before the named boundary. Nearest and earliest anchors are candidates, never defaults.
+Name the boundary before choosing a target. Timeline reports evidence; it does not decide. A target must sit before the named boundary. Nearest and earliest anchors are candidates against boundary and cold start—not answers by proximity.
 
-### Rebase gate
+### Rebase criteria
 
-A **rebase** is a structural reset across accumulated summary depth. It uses the fold gate and adds two completion criteria: **structural reset** and **cold start**.
+A **rebase** is a structural reset across accumulated summary depth. It uses the fold criteria and adds two completion criteria: **structural reset** and **cold start**.
 
 Structural reset passes only when the target precedes an active `branch_summary` that leaves the spine and projected summary depth does not grow. Equal depth passes only when the new snapshot replaces an old summary; a target after all active summaries fails.
 
 Cold start passes only when `NEXT` is immediately executable, every surviving front and invariant is in the snapshot or a usable direct pointer, and ordinary execution needs no archived summary.
 
-Build one authoritative snapshot, then evaluate candidate bases from earliest to latest. Choose the earliest base that passes both criteria. Root is ideal when it passes; it is never presumed safe.
+Build one authoritative snapshot, then evaluate candidates from earliest to latest. Choose the earliest base that passes both criteria. Root is ideal when it passes; treat it as a candidate until both criteria clear.
 
 If no candidate passes, rebase is not ready: keep required detail live, use a local fold, or accept native compaction.
 
-### Handoff contract
+### Handoff shape
 
-Every handoff uses these seven slots in this order. Write `none` when a category is empty.
+Every handoff uses these seven slots in order. Write `none` when empty. Evidence is a pointer index, not a dump of the folded trail.
 
 ```text
 Goal: <current goal; quote a new triggering request when its turn will leave context>
@@ -75,12 +81,14 @@ Recover: <archive checkpoint, backup label, or raw node pointer>
 NEXT: <one executable next action>
 ```
 
-The runtime can validate slot structure. Semantic completeness, target quality, recoverability sufficiency, and whether NEXT is genuinely executable remain agent completion criteria.
+The runtime validates slot structure. Semantic completeness, target quality, recoverability, and whether NEXT is executable remain agent completion criteria.
 
 ### Representative transitions
 
 **Local fold example**
 
+Why: findings are distilled; raw trail is unused by NEXT; Recover keeps the burst archive.
+
 ```text
 Goal: Fix high CPU while preserving the sidebar.
 State: Profiling proved hidden tabs retain workers; implementation is next.
@@ -93,6 +101,8 @@ NEXT: Checkpoint sidebar-lifecycle-fix-start, then inspect worker disposal.
 
 **Finished-chain rebase example**
 
+Why: prior chain is stable; one cold-start snapshot carries the new request from the earliest safe base.
+
 Rebase the finished chain to the earliest base that passes cold start:
 
 ```text
@@ -105,15 +115,15 @@ Recover: release-fix-done.
 NEXT: Checkpoint migration-dry-run-start, then inspect the migration command entry point.
 ```
 
-After travel, confirm resolved target, summary leaf, backup outcome, raw usage/message/summary-depth deltas, and context-sync state. After a rebase, execute from the snapshot without rereading archived summaries. If NEXT begins a new phase, checkpoint that phase before acting. Travel changes conversation context only; inspect disk and external systems directly.
+After travel, confirm resolved target, summary leaf, backup outcome, raw usage/message/summary-depth deltas, and context-sync state. After a rebase, execute from the snapshot—archived summaries stay archive. If NEXT begins a new phase, checkpoint that phase before acting. Travel changes conversation context only; inspect disk and external systems directly.
 <!-- ACM:CORE:END -->
 
 <!-- ACM:TOOL_CHECKPOINT:START -->
-Preflight a distinct user goal on the branch that will carry it: after any required finished-chain transition and before managed work, call this tool with a semantic `-start` name. Also checkpoint later phase, attempt, burst, risky step, pause, milestone, or completion boundaries with a semantic `-start`, `-paused`, or `-done` name. Names are unique across the session tree and case-sensitive. Omitting target labels the nearest meaningful USER/AI turn; an explicit checkpoint name or node ID can label older history. This tool creates recoverability by labeling history without branching or folding the active context.
+Preflight a distinct user goal on the branch that will carry it: after any finished-chain transition and before managed work makes rewind expensive, call this tool with a semantic `-start` name. Also checkpoint later phase, attempt, burst, risky step, pause, milestone, or completion boundaries with a semantic `-start`, `-paused`, or `-done` name. Names are unique across the session tree and case-sensitive. Omitting target labels the nearest meaningful USER/AI turn; an explicit checkpoint name or node ID can label older history. This tool creates recoverability by labeling history without branching or folding the active context.
 <!-- ACM:TOOL_CHECKPOINT:END -->
 
 <!-- ACM:TOOL_TIMELINE:START -->
-Inspect session structure and context evidence through one view: `active`, `checkpoints`, `search`, or `tree`. Omit view for `active`. Timeline reports active summary depth and projected depth for candidate bases. Use `checkpoints` or `search` to compare non-obvious targets; use `tree` only when topology matters. Choose a target by boundary or cold start, not proximity.
+Inspect session structure and context evidence through one view: `active`, `checkpoints`, `search`, or `tree`. Omit view for `active`. Timeline reports active summary depth and projected depth for candidate bases. Use `checkpoints` or `search` to compare candidates against the named boundary or cold start; use `tree` only when topology matters. Choose by boundary or cold start, not by proximity or anchor gravity.
 <!-- ACM:TOOL_TIMELINE:END -->
 
 <!-- ACM:TOOL_TRAVEL:START -->
@@ -125,15 +135,15 @@ Recoverability created. Continue the current working set; choose any later fold
 <!-- ACM:CUE_CHECKPOINT_START:END -->
 
 <!-- ACM:CUE_CHECKPOINT_DONE:START -->
-Milestone archived. Use it as a recovery pointer. If this closes a stable chain or another fold would stack, run a rebase check before continuing.
+Milestone archived. Use it as a recovery pointer. If this closes a stable chain or another fold would stack, run a rebase check against the working-set invariant before continuing.
 <!-- ACM:CUE_CHECKPOINT_DONE:END -->
 
 <!-- ACM:CUE_TIMELINE_ACTIVE:START -->
 View `active` selected. Continue from the visible spine; inspect another view only when target identity or branch topology is not yet checkable.
 <!-- ACM:CUE_TIMELINE_ACTIVE:END -->
 
 <!-- ACM:CUE_REBASE_CHECK:START -->
-Active summarized history is present. When the current event is a rebase trigger or the next fold would stack, test structural reset and cold start from the earliest safe base; root is a candidate, not a verdict.
+Active summarized history is present. When the current situation is a rebase trigger or the next fold would stack, test structural reset and cold start from the earliest safe base; root is a candidate, not a verdict.
 <!-- ACM:CUE_REBASE_CHECK:END -->
 
 <!-- ACM:CUE_TIMELINE_CHECKPOINTS:START -->
@@ -149,15 +159,15 @@ View `tree` selected. Use branch topology to verify front ownership and target p
 <!-- ACM:CUE_TIMELINE_TREE:END -->
 
 <!-- ACM:CUE_TRAVEL_PHASE:START -->
-Checkpoint the next phase before its first action, then execute the handoff NEXT.
+Anchor the next phase with a checkpoint, then execute the handoff NEXT.
 <!-- ACM:CUE_TRAVEL_PHASE:END -->
 
 <!-- ACM:CUE_TRAVEL_TASK:START -->
-Answer from the handoff branch; do not reintroduce archived process into the final response.
+Answer from the handoff working set; keep the final response free of archived process detail.
 <!-- ACM:CUE_TRAVEL_TASK:END -->
 
 <!-- ACM:RECOVERY_NAME_COLLISION:START -->
-Search existing checkpoints, preserve the semantic base, and add the smallest useful scope, ordinal, or date. Do not overwrite the existing recovery target.
+Search existing checkpoints, preserve the semantic base, and add the smallest useful scope, ordinal, or date. Leave the existing recovery target unchanged.
 <!-- ACM:RECOVERY_NAME_COLLISION:END -->
 
 <!-- ACM:RECOVERY_HOST_CAPABILITY:START -->

skills/context-management/SKILL.md

@@ -5,7 +5,7 @@ description: "Resolve advanced ACM cases: ambiguous earliest-safe-base selection
 
 # Advanced Context Management
 
-The always-on **CORE owns the normal path**: ordinary checkpointing, clear phase folds, clear burst folds, pressure checks, task-end handling, and an obvious rebase all stay there. This Skill resolves one advanced condition at a time.
+The always-on **CORE owns the normal path**: the working-set invariant, ordinary checkpointing, clear phase folds, clear burst folds, rebase checks under pressure, task-end handling, and an obvious rebase all stay there. This Skill resolves one advanced condition at a time.
 
 Select the reference whose observable condition is active:
 

src/checkpoint-tool.ts

@@ -47,7 +47,7 @@ export function registerCheckpointTool(pi: ExtensionAPI): void {
     description: TOOL_DESCRIPTIONS.checkpoint,
     promptSnippet: "Label a recoverable session boundary without changing context",
     promptGuidelines: [
-      "Use acm_checkpoint to preflight each distinct user goal before managed work and to label later phase, burst, pause, milestone, or completion boundaries.",
+      "Use acm_checkpoint to preflight each distinct user goal before managed work makes rewind expensive, and to label later phase, burst, pause, milestone, or completion boundaries.",
     ],
     parameters: schema,
     renderShell: "self",

src/context-usage-nudge.ts

@@ -154,17 +154,17 @@ export function buildContextUsageNudgeMessage(nudge: PendingContextUsageNudge):
 
   const guidance = nudge.level === 30
     ? [
-        "Continue the current work normally. At the next natural semantic boundary, consider whether current task requirements permit a safe fold or rebase travel.",
-        "Travel is optional, but keeping the active context small is preferred when it can be done without losing needed working state.",
+        "Continue the current work normally. At the next natural semantic boundary, ask whether the working-set invariant still holds and whether the fold criteria can pass.",
+        "Prefer a smaller active working set when a complete handoff can preserve needed state and make NEXT executable; otherwise keep required detail live.",
       ]
     : nudge.level === 50
       ? [
-          "Context pressure is becoming material. Based on the current task requirements, actively look for the next safe opportunity for a fold or rebase travel.",
-          "Travel is recommended when a complete handoff can preserve the required working state and make NEXT executable. Do not travel if important context is still needed, but prefer returning to a smaller active context when safely possible.",
+          "Context pressure is becoming material. Raise the priority of a rebase check, and actively look for the next boundary where fold criteria and cold start can pass.",
+          "Travel earns its place only when the handoff preserves required working state and makes NEXT executable. Prefer restoring a smaller working set when those criteria hold.",
         ]
       : [
-          "Context pressure is high. At the earliest safe semantic boundary, strongly consider a fold or rebase travel if current task requirements allow a complete and recoverable handoff.",
-          "Keeping the active context small is strongly preferred, but correctness, task continuity, and recoverability take priority. If no safe travel is available, continue normally; native compaction is acceptable for a genuinely long task.",
+          "Context pressure is high. At the earliest safe semantic boundary, prefer a fold or rebase when fold criteria and cold start pass.",
+          "Correctness, task continuity, recoverability, and cold start outrank pressure. If no safe transition is available, continue with required detail live; native compaction is acceptable for a genuinely long task.",
         ];
 
   return {