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:
2026-04-14 10:40:57 +00:00
committed by Forgejo
parent 70b064e877
commit 7ba1e5737f
3 changed files with 62 additions and 0 deletions
+51
View File
@@ -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"