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

@@ -164,6 +164,16 @@ ensuring data is stored with proper parameter values.
   LLM streaming output. A `SessionActorNotConfiguredError` is raised with exit
   code 1 when no actor is configured.
 
+### 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()`

CONTRIBUTORS.md

@@ -64,3 +64,4 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the Definition-of-Done gating feature for the Apply phase (PR #8299 / issue #7927): `PlanLifecycleService.apply_plan` now evaluates DoD criteria before transitioning to Apply, raising `DoDGatingError` when required criteria fail and storing evaluation results in `plan.validation_summary`.
 * 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 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.

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"