refactor(acm): optimal dao-shu guidance — Composer synthesis of #4+#5

scripts/generate-guidance.test.mjs

@@ -126,6 +126,7 @@ describe("canonical guidance generation", () => {
     }
     expect(GUIDANCE_CUES.rebaseCheck).toContain("Active summarized history is present");
     expect(GUIDANCE_CUES.rebaseCheck).toContain("structural reset and cold start");
+    expect(GUIDANCE_CUES.rebaseCheck).toContain("cold-start test passes");
     expect(GUIDANCE_CUES.timelineActive).toContain("`active`");
     expect(GUIDANCE_CUES.timelineCheckpoints).toContain("`checkpoints`");
     expect(GUIDANCE_CUES.timelineSearch).toContain("`search`");

skills/context-management/CORE.md

@@ -5,11 +5,11 @@ This file is the editable source for always-on ACM guidance and generated tool/r
 <!-- ACM:CORE:START -->
 ## Agentic Context Management CORE v1
 
-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**.
+A context window is a **working set**: the exact material needed for the next action. Process detail accumulates naturally; keep live what NEXT needs. 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,24 @@ 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—opening a **managed chain**. After any needed finished-chain transition (see Recognizable moments), 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 the checkpoint was created or reused. If the call fails, follow the recovery guidance in its result before proceeding. A **lightweight reply**—no evidence lookup, side effects, or multi-step reasoning—stays outside.
+
+### Decision smells
+
+These observables are quick checks against the working-set invariant—worth pausing for, not automatic commands:
+
+- **Nearest checkpoint feels obvious** — **anchor gravity**; name the boundary before choosing a target.
+- **Summary upon summary** — rebase trigger; test structural reset and **cold start** from the earliest safe base.
+- **User goal changed over finished work** — fold or rebase the prior chain before the new one starts.
+- **Exploration done, implementation next** — raw burst can leave once distilled into the handoff.
+
+### Recognizable moments
 
-| 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:
+
+| What you can observe | What becomes reasonable |
 |---|---|
 | 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 +50,42 @@ 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**. Travel earns its place only when the fold gate—and any rebase criteria—still pass.
 
 ### Fold gate
 
-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.
+Before `acm_travel`, answer in one line: what leaves, what pointer recovers it, and what single action is NEXT.
 
-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
 
-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 gate and adds **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. Root is ideal when it passes; treat it as a candidate until both clear.
+
+If no candidate passes, rebase is not ready: keep required detail live, use a local fold, or accept native compaction. Ambiguous base selection, interleaved fronts, or raw-node fallback → load the context-management skill.
+
+### Failure shapes
 
-If no candidate passes, rebase is not ready: keep required detail live, use a local fold, or accept native compaction.
+- **Folded too early** — NEXT stalls; archived detail is needed again.
+- **Folded too late** — working set bloats; context pressure rises.
+- **Wrong target** — a parked front, invariant, or recovery pointer vanishes from the spine.
+- **Rebase skipped** — summaries stack; cold start degrades across folds.
 
-### 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 +97,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 and rejects mixed tool batches. 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 +117,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,35 +131,37 @@ 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.
+
+For archive round trips, name collisions, travel failure, indeterminate mutation, exhausted refresh, or ambiguous bases → load the context-management skill.
 <!-- 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 `<chain>-start` name so the managed chain can begin. Also label 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 -->
-Apply one recoverable context transition: fold a named boundary or rebase accumulated summaries to the earliest safe base. Resolve a checkpoint, node ID, or root; complete validation before mutation; optionally bookmark the abandoned raw path. Use timeline evidence for target comparison. Travel reports structural and context deltas but cannot prove boundary quality or cold start completeness. It must run alone in its assistant tool batch; mixed tool batches are rejected before mutation.
+Apply one recoverable context transition: fold a named boundary or rebase accumulated summaries to the earliest safe base. Resolve a checkpoint, node ID, or root; complete validation before mutation; optionally bookmark the abandoned raw path. Use timeline evidence for target comparison. Travel reports structural and context deltas but cannot prove boundary quality or cold start completeness. Mixed tool batches are rejected before mutation.
 <!-- ACM:TOOL_TRAVEL:END -->
 
 <!-- ACM:CUE_CHECKPOINT_START:START -->
-Recoverability created. Continue the current working set; choose any later fold target by boundary, not by nearest-anchor gravity.
+Recoverability confirmed. Continue the current working set; any later fold target is chosen by boundary, not nearest-anchor gravity.
 <!-- 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 passes only when the cold-start test passes.
 <!-- ACM:CUE_REBASE_CHECK:END -->
 
 <!-- ACM:CUE_TIMELINE_CHECKPOINTS:START -->
@@ -149,15 +177,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.
+Final answer sources the handoff snapshot only; archived process stays off the spine.
 <!-- 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, decision smells, recognizable moments, fold and rebase gates, 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 when CORE's gates pass but the decision remains ambiguous or a result reports an exceptional outcome.
 
 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",