From d61bebbfe65292b03fb0fff24c6ea5c2d0ae2d9d Mon Sep 17 00:00:00 2001 From: CleverThis Date: Tue, 14 Apr 2026 10:40:57 +0000 Subject: [PATCH] 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 --- CHANGELOG.md | 10 +++++++++ CONTRIBUTORS.md | 1 + docs/specification.md | 51 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d8568c18..98ee42cf0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -174,6 +174,16 @@ ensuring data is stored with proper parameter values. `src/cleveragents/cli/commands/plan.py` to show correct positional argument order. CONTRIBUTING.md updated with the required CLI docstring example style guide. +### Documentation + +- **`context_tier_hydrator` module documented in ACMS architecture section** (#9208): Added + a new **Context Tier Hydration** subsection to the ACMS Architecture section of the + specification (`docs/specification.md`), 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, os.walk fallback), budget limits (256 KB per file, + 10 MB total per project), and fragment structure (`TieredFragment` with HOT tier placement + and metadata keys `path`, `detail_depth`, `relevance_score`). Closes #6175. + ### Fixed - **fileConfig error handling in alembic env.py** (#7874): Wrapped the `fileConfig()` diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 54802c6bc..7fe685040 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -66,3 +66,4 @@ Below are some of the specific details of various contributions. * HAL 9000 has contributed the engine cache TOCTOU race condition fix (PR #8265 / issue #7566): added `MEMORY_ENGINES_LOCK` to `engine_cache.py` and wrapped the check-and-set operation in `UnitOfWork.engine` with `with MEMORY_ENGINES_LOCK:` to prevent concurrent threads from creating duplicate in-memory SQLite engine instances; also fixed a cache-hit bug where `self._engine` was never assigned on a cache hit. * HAL 9000 has contributed the plan correct JSON output envelope fix (PR #8662 / issue #8584): restructured `agents plan correct --format json` output to nest correction fields under `data.correction` and pass `command="plan correct"` to `format_output`, producing the spec-required CLI envelope. Added three BDD scenarios validating `data.correction.mode` (revert and append modes) and the `command` field. * HAL 9000 has contributed BDD feature file tag coverage improvements (#9124 / pr #9183): added required `@a2a`, `@session`, and `@cli` Gherkin tags to 30 feature files (8 A2A, 7 session, 15 CLI) to enable selective tag-based test filtering via `behave --tags=a2a,session,cli`. +* HAL 9000 has contributed the ACMS Context Tier Hydration documentation (PR #9208 / issue #6175): documented the `context_tier_hydrator` module in the ACMS Architecture section of the specification, covering its public interface, file listing strategy, budget limits, and fragment structure. diff --git a/docs/specification.md b/docs/specification.md index a87242b32..f0e997993 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -45782,6 +45782,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"