Proposal: update specification — document context_tier_hydrator module in ACMS architecture section #6175

New issue

Open

opened 2026-04-09 17:10:11 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 17:10:11 +00:00

Owner

Specification Update Proposal

Triggered by: Merged PR #4219 (fix(acms): wire ACMS indexing pipeline into CLI so ContextTierService is populated during context operations)

What Changed in the Implementation

PR #4219 introduced a new module src/cleveragents/application/services/context_tier_hydrator.py that:

Bridges the gap between the resource registry (files on disk) and the ACMS context tier (in-memory fragments)
Provides two public functions:
- hydrate_tiers_for_plan(tier_service, project_names, project_repository, resource_registry) -> int — hydrates all projects linked to a plan
- hydrate_tiers_from_project(tier_service, project_name, resource_id, resource_location, resource_type) -> int — hydrates a single project resource
Uses git ls-files for git-checkout resources, falls back to os.walk for others
Enforces limits: max 256 KB per file, max 10 MB total per project
Skips binary files and common non-source directories (.git, node_modules, __pycache__, etc.)
Stores TieredFragment objects in ContextTierService with ContextTier.HOT tier
Metadata values detail_depth and relevance_score are stored as strings (not int/float) — this was a bug fix in PR #5998

This module resolves bug #1028 where ContextTierService started empty on every CLI invocation, leaving the LLM with zero file context during plan execution.

What Spec Section(s) Need Updating

Current spec state: The context_tier_hydrator module does not appear anywhere in the 47,040-line specification. The ACMS section (§Architecture, ~line 43167+) describes the ACMS pipeline conceptually but does not document the hydration step that populates ContextTierService before context assembly.

Proposed addition: Add a subsection to the ACMS architecture section (§Architecture → ACMS) documenting:

Context Tier Hydration — the process of populating ContextTierService from linked project resources before context assembly
context_tier_hydrator module — its two public functions, their signatures, and their behavior
File listing strategy — git ls-files for git-checkout resources, os.walk fallback
Size/budget limits — 256 KB per file, 10 MB total per project
Fragment structure — TieredFragment with ContextTier.HOT, metadata keys path, detail_depth (string), relevance_score (string)
Integration point — hydration runs before context assembly in LLMExecuteActor.execute()

Rationale

The implementation discovered a critical missing step in the ACMS pipeline: without hydration, the LLM receives zero file context. This is a genuine architectural improvement that the spec must document. The hydration module is a stable, tested component (6 Behave scenarios) that is now part of the production code path.

Scope

Section: ## Architecture → ACMS subsection (~line 43167+)
Change type: Addition (new subsection)
Size: ~30-50 lines of new spec content
Impact: No existing spec content needs to be removed or changed; this is purely additive

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Specification Update Proposal **Triggered by**: Merged PR #4219 (`fix(acms): wire ACMS indexing pipeline into CLI so ContextTierService is populated during context operations`) --- ## What Changed in the Implementation PR #4219 introduced a new module `src/cleveragents/application/services/context_tier_hydrator.py` that: 1. Bridges the gap between the resource registry (files on disk) and the ACMS context tier (in-memory fragments) 2. Provides two public functions: - `hydrate_tiers_for_plan(tier_service, project_names, project_repository, resource_registry) -> int` — hydrates all projects linked to a plan - `hydrate_tiers_from_project(tier_service, project_name, resource_id, resource_location, resource_type) -> int` — hydrates a single project resource 3. Uses `git ls-files` for git-checkout resources, falls back to `os.walk` for others 4. Enforces limits: max 256 KB per file, max 10 MB total per project 5. Skips binary files and common non-source directories (`.git`, `node_modules`, `__pycache__`, etc.) 6. Stores `TieredFragment` objects in `ContextTierService` with `ContextTier.HOT` tier 7. Metadata values `detail_depth` and `relevance_score` are stored as **strings** (not int/float) — this was a bug fix in PR #5998 This module resolves bug #1028 where `ContextTierService` started empty on every CLI invocation, leaving the LLM with zero file context during plan execution. --- ## What Spec Section(s) Need Updating **Current spec state**: The `context_tier_hydrator` module does not appear anywhere in the 47,040-line specification. The ACMS section (§Architecture, ~line 43167+) describes the ACMS pipeline conceptually but does not document the hydration step that populates `ContextTierService` before context assembly. **Proposed addition**: Add a subsection to the ACMS architecture section (§Architecture → ACMS) documenting: 1. **Context Tier Hydration** — the process of populating `ContextTierService` from linked project resources before context assembly 2. **`context_tier_hydrator` module** — its two public functions, their signatures, and their behavior 3. **File listing strategy** — `git ls-files` for git-checkout resources, `os.walk` fallback 4. **Size/budget limits** — 256 KB per file, 10 MB total per project 5. **Fragment structure** — `TieredFragment` with `ContextTier.HOT`, metadata keys `path`, `detail_depth` (string), `relevance_score` (string) 6. **Integration point** — hydration runs before context assembly in `LLMExecuteActor.execute()` --- ## Rationale The implementation discovered a critical missing step in the ACMS pipeline: without hydration, the LLM receives zero file context. This is a genuine architectural improvement that the spec must document. The hydration module is a stable, tested component (6 Behave scenarios) that is now part of the production code path. --- ## Scope - **Section**: `## Architecture` → ACMS subsection (~line 43167+) - **Change type**: Addition (new subsection) - **Size**: ~30-50 lines of new spec content - **Impact**: No existing spec content needs to be removed or changed; this is purely additive --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

Rows
Columns