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
 

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)