docs(spec): document context_tier_hydrator module in ACMS architecture section
Adds Context Tier Hydration subsection to the ACMS Architecture section of the specification, documenting the context_tier_hydrator module's public interface (hydrate_tiers_for_plan, hydrate_tiers_from_project), file listing strategy (git ls-files for git-checkout resources, os.walk fallback), budget limits (256 KB per file, 10 MB total per project), and fragment structure (TieredFragment with ContextTier.HOT placement, metadata keys path/detail_depth/relevance_score). Also updates CHANGELOG.md under [Unreleased] > Documentation and adds contribution entry to CONTRIBUTORS.md. ISSUES CLOSED: #6175
This commit is contained in:
@@ -45928,6 +45928,57 @@ Organizations can adopt ACMS features progressively. At each stage, existing res
|
||||
|
||||
This design ensures agents never wait for index building during execution, providing a responsive and predictable experience even on massive codebases.
|
||||
|
||||
#### Context Tier Hydration
|
||||
|
||||
Before context assembly begins, `ContextTierService` must be populated from the project's linked resources. This hydration step is performed by the `context_tier_hydrator` module (`src/cleveragents/application/services/context_tier_hydrator.py`).
|
||||
|
||||
**Integration Point:** Hydration runs inside `LLMExecuteActor.execute()` before the context assembly pipeline is invoked. Without this step, `ContextTierService` starts empty on every CLI invocation and the LLM receives zero file context.
|
||||
|
||||
**Public Interface:**
|
||||
|
||||
```python
|
||||
def hydrate_tiers_for_plan(
|
||||
tier_service: ContextTierService,
|
||||
project_names: list[str],
|
||||
project_repository: ProjectRepository,
|
||||
resource_registry: ResourceRegistry,
|
||||
) -> int:
|
||||
"""Hydrate all projects linked to a plan. Returns total fragment count."""
|
||||
|
||||
def hydrate_tiers_from_project(
|
||||
tier_service: ContextTierService,
|
||||
project_name: str,
|
||||
resource_id: str,
|
||||
resource_location: str,
|
||||
resource_type: str,
|
||||
) -> int:
|
||||
"""Hydrate a single project resource. Returns fragment count."""
|
||||
```
|
||||
|
||||
**File Listing Strategy:**
|
||||
|
||||
- For `git-checkout` resources: uses `git ls-files` to enumerate tracked files only
|
||||
- For all other resource types: falls back to `os.walk` directory traversal
|
||||
|
||||
**Budget Limits (per project):**
|
||||
|
||||
- Maximum file size: 256 KB — files exceeding this limit are skipped
|
||||
- Maximum total size: 10 MB — hydration stops when the per-project budget is exhausted
|
||||
- Binary files are skipped automatically
|
||||
- Common non-source directories are excluded: `.git`, `node_modules`, `__pycache__`, `.venv`, `dist`, `build`
|
||||
|
||||
**Fragment Structure:**
|
||||
|
||||
Each file is stored as a `TieredFragment` in `ContextTierService` with:
|
||||
|
||||
- `tier`: `ContextTier.HOT` (all hydrated fragments start in the hot tier)
|
||||
- `metadata["path"]`: relative file path (string)
|
||||
- `metadata["detail_depth"]`: depth indicator (string, not int)
|
||||
- `metadata["relevance_score"]`: relevance score (string, not float)
|
||||
|
||||
!!! note
|
||||
`detail_depth` and `relevance_score` are stored as strings. This was a deliberate fix (PR #5998) — earlier versions stored these as numeric types, causing serialization inconsistencies.
|
||||
|
||||
### Storage and Persistence
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
|
||||
Reference in New Issue
Block a user