1 changed files with 24 additions and 0 deletions
@@ -25335,6 +25335,30 @@ The system is designed around the hierarchical nature of plans: parent plans see

 **Critical Design Decision**: All indexing happens immediately when resources are added to projects or when code changes. There is no "on-demand" indexing during agent execution. This ensures that agents always have instant access to search capabilities without any indexing delays. The computational cost is paid once upfront, not repeatedly during agent operations.

+!!! note "Context Tier Hydration (Bridge Implementation)"
+
+    **Context Tier Hydration** is a lightweight bridge that populates the in-memory `ContextTierService` from linked project resources at the start of each plan execution. This is distinct from full ACMS indexing (which builds UKO ontology graphs, computes embeddings, and persists index state). Hydration is necessary because `ContextTierService` is an in-memory service that does not persist across CLI process invocations.
+
+    **When hydration runs**: Automatically before context assembly in `LLMExecuteActor.execute()`, for every project linked to the plan.
+
+    **Hydration algorithm**:
+
+    1. For each project linked to the plan, retrieve the project's linked resources from the resource registry.
+    2. For each linked resource with a valid filesystem location:
+       - If the resource is a `git-checkout` type: list tracked files via `git ls-files --cached --others --exclude-standard`
+       - Otherwise: walk the directory tree via `os.walk`, skipping hidden directories and known non-code directories (`.git`, `node_modules`, `__pycache__`, `.venv`, etc.)
+    3. For each file:
+       - Skip binary file extensions (`.pyc`, `.so`, `.png`, `.pdf`, etc.)
+       - Skip files larger than 256 KB
+       - Stop if total bytes indexed exceeds 10 MB per project
+       - Read file content as UTF-8 (skip on decode error)
+       - Store as a `TieredFragment` in the `HOT` tier with `detail_depth=1`, `relevance_score=0.5`
+    4. Log the number of fragments stored.
+
+    **Relationship to the Critical Design Decision**: The "no on-demand indexing" principle applies to the full UKO/ACMS indexing pipeline (ontology graph construction, embedding computation, persistent index updates). Context tier hydration is a lightweight file-read operation that populates the hot tier with raw file content — it is not the same as full ACMS indexing. When the full ACMS indexing pipeline is implemented with persistent index state, this hydration step will be replaced by reading from the persisted index.
+
+    **Module**: `cleveragents.application.services.context_tier_hydrator`
+
 > The full architectural design of the ACMS -- including the UKO ontology hierarchy, backend abstraction layer, Context Assembly Pipeline (the 10-component pluggable pipeline that replaced the former Strategy Coordinator and Fusion Engine), index synchronization, performance characteristics, and plugin architecture -- is specified in the **Architecture > ACMS Architecture** section.

 #### Core Data Types