From 1f64a274e3fbc17ac95157c010e1881020ea65c6 Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Sun, 5 Apr 2026 21:31:44 +0000 Subject: [PATCH] docs: document ACMS real retrieval logic and automatic checkpoint triggers - docs/reference/context_strategies.md: update Built-in Strategies table to document real retrieval logic for all 6 strategies (SimpleKeyword, SemanticEmbedding, BreadthDepthNavigator, ARCE, TemporalArchaeology, PlanDecisionContext); add note about v1 character-frequency embedding approximation; note SpecStrategyAdapter registration (#3500) - docs/reference/checkpointing.md: add Automatic Checkpoint Triggers section documenting the 4 triggers (on_tool_write, on_tool_write_complete, on_subplan_spawn, on_error), configuration via core.checkpoints.auto_create_on, and wiring into ToolRunner/SubplanExecutionService/PlanExecutor (#3439) --- docs/reference/checkpointing.md | 45 ++++++++++++++++++++++++++-- docs/reference/context_strategies.md | 25 +++++++++++----- 2 files changed, 59 insertions(+), 11 deletions(-) diff --git a/docs/reference/checkpointing.md b/docs/reference/checkpointing.md index 829369eaa..829dc3a78 100644 --- a/docs/reference/checkpointing.md +++ b/docs/reference/checkpointing.md @@ -58,13 +58,52 @@ The rollback operation enforces two guards: 2. **Sandbox is missing** — If the sandbox has been cleaned up, rollback is rejected because there is nothing to restore. +## Automatic Checkpoint Triggers (v3.8.0+) + +The execution engine now supports four automatic checkpoint triggers, all +configurable via `core.checkpoints.auto_create_on` (default: all enabled): + +| Trigger | When | Component | +|---------|------|-----------| +| `on_tool_write` | Before each write-tool execution | `ToolRunner` | +| `on_tool_write_complete` | After each write-tool execution | `ToolRunner` | +| `on_subplan_spawn` | Before first subplan execution attempt | `SubplanExecutionService` | +| `on_error` | When the Execute phase fails | `PlanExecutor` | + +### Configuration + +```toml +[core.checkpoints] +auto_create_on = ["on_tool_write", "on_tool_write_complete", "on_subplan_spawn", "on_error"] +``` + +To disable a specific trigger, remove it from the list. To disable all +automatic checkpoints: + +```toml +[core.checkpoints] +auto_create_on = [] +``` + +### Wiring + +The `CheckpointService` is injected as an optional parameter into: + +- **`ToolRunner`** — `checkpoint_service` and `auto_checkpoint_triggers` parameters +- **`SubplanExecutionService`** — `checkpoint_service`, `auto_checkpoint_triggers`, and `parent_plan_id` parameters +- **`PlanExecutor`** — uses `_is_auto_trigger_active()` helper to check trigger config + +When `checkpoint_service` is `None`, all automatic checkpointing is skipped +(backward-compatible no-op). + ## CLI Usage ### Create a checkpoint (programmatic) -Checkpoints are typically created automatically by the execution engine -before and after tool invocations, controlled by the `CheckpointScope` -on each tool's capability declaration. +Checkpoints are created automatically by the execution engine via the four +triggers above, or manually via `CheckpointService.create_checkpoint()`. +The `CheckpointScope` on each tool's capability declaration controls which +tools trigger `on_tool_write` / `on_tool_write_complete` checkpoints. ### Rollback to a checkpoint diff --git a/docs/reference/context_strategies.md b/docs/reference/context_strategies.md index 81b6afa56..ad69b51ca 100644 --- a/docs/reference/context_strategies.md +++ b/docs/reference/context_strategies.md @@ -52,18 +52,27 @@ Every strategy implements: ## Built-in Strategies -| Strategy | Quality | Backends | Description | -|----------|---------|----------|-------------| -| `simple-keyword` | 0.3 | Text | Basic keyword/regex text search. Universal fallback. | -| `semantic-embedding` | 0.6 | Vector | Vector similarity search. | -| `breadth-depth-navigator` | 0.85 | Graph | Graph-aware UKO traversal. Primary code-aware strategy. | -| `arce` | 0.95 | All | Multi-modal ARCE pipeline. Highest quality. | -| `temporal-archaeology` | 0.5 | Graph + Cold | Historical pattern discovery. | -| `plan-decision-context` | 0.7 | Warm/Cold | Parent/ancestor plan context retrieval. | +All six built-in strategies now implement real backend-driven retrieval logic +(v3.8.0+, issue #3500). Previously they were no-op stubs that returned empty +fragment lists. The `SpecStrategyAdapter` bridges each strategy into the +`ACMSPipeline` at construction time. + +| Strategy | Quality | Backends | Retrieval Logic | +|----------|---------|----------|-----------------| +| `simple-keyword` | 0.3 | Text | `TextBackend.search()` using keywords extracted from the `ContextRequest`; results packed greedily into token budget | +| `semantic-embedding` | 0.6 | Vector | `VectorBackend.similarity_search()` using a character-frequency embedding as a v1 approximation; budget-aware packing | +| `breadth-depth-navigator` | 0.85 | Graph | `GraphBackend` traversal from focus nodes declared in the `ContextRequest`, expanding outward by `request.breadth` hops | +| `arce` | 0.95 | All | Multi-modal pipeline: text search (40% budget) + vector similarity (40%) + graph traversal (20%); results merged and deduplicated | +| `temporal-archaeology` | 0.5 | Graph + Cold | Two-phase: `TemporalBackend.query_by_tier()` for cold-tier historical nodes, then `GraphBackend` traversal from those nodes | +| `plan-decision-context` | 0.7 | Warm/Cold | `TemporalBackend`-driven lookup walking parent and ancestor plan hierarchy, retrieving decision records from warm/cold tiers | Default enabled (spec `context.strategies.enabled`): `["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]` +> **Note:** The `SemanticEmbeddingStrategy` uses a character-frequency +> embedding as a v1 approximation of semantic similarity. A real embedding +> model integration is planned for a future milestone. + ## Configuration ### Global (config.toml) -- 2.52.0