# Протокол Семантического Обогащения (Semantic Enrichment Protocol)
**Версия: 1.1**

## Описание
Этот документ является единственным источником истины для правил, которые должны соблюдаться в кодовой базе. Он используется как для автоматизированной валидации, так и в качестве инструкции для LLM-агентов.

---

## Правила

### 1. Целостность Заголовка Файла (`FileHeaderIntegrity`)
Каждый `.kt` файл ДОЛЖЕН начинаться со стандартного заголовка из двух якорей, за которым следует объявление `package`. Заголовок служит 'паспортом' файла.

**Пример:**
```kotlin
// [FILE] YourFileName.kt
// [SEMANTICS] ui, viewmodel, state_management

package com.example.your.package.name
```

### 2. Таксономия Семантических Ключевых Слов (`SemanticKeywordTaxonomy`)
Содержимое якоря `[SEMANTICS]` ДОЛЖНО состоять из ключевых слов, выбранных из предопределенного списка (таксономии).

**Допустимые значения:**
*   **Layer:** `ui`, `domain`, `data`, `presentation`
*   **Component:** `viewmodel`, `usecase`, `repository`, `service`, `screen`, `component`, `dialog`, `model`, `entity`, `activity`, `application`, `nav_host`, `controller`, `navigation_drawer`, `scaffold`, `dashboard`, `item`, `label`, `location`, `setup`, `theme`, `dependencies`, `custom_field`, `statistics`, `image`, `attachment`, `item_creation`, `item_detailed`, `item_summary`, `item_update`, `summary`, `update`
*   **Concern:** `networking`, `database`, `caching`, `authentication`, `validation`, `parsing`, `state_management`, `navigation`, `di`, `testing`, `entrypoint`, `hilt`, `timber`, `compose`, `actions`, `routes`, `common`, `color_selection`, `loading`, `list`, `details`, `edit`, `label_management`, `labels_list`, `dialog_management`, `locations`, `sealed_state`, `parallel_data_loading`, `timber_logging`, `dialog`, `color`, `typography`, `build`, `data_transfer_object`, `dto`, `api`, `item_creation`, `item_detailed`, `item_summary`, `item_update`, `create`, `mapper`, `count`, `user_setup`, `authentication_flow`
*   **LanguageConstruct:** `sealed_class`, `sealed_interface`
*   **Pattern:** `ui_logic`, `ui_state`, `data_model`, `immutable`

### 3. Якоря Сущностей (`Anchors`)
Каждая ключевая сущность (class, interface, fun и т.д.) ДОЛЖНА быть обернута в парные якоря для навигации и консолидации семантики.

**Синтаксис:**
- **Открывающий якорь:** `// [ANCHOR:id:type]`
- **Закрывающий якорь:** `// [END_ANCHOR:id]`

**Пример:**
```kotlin
// [ANCHOR:Success:DataClass]
/**
 * @summary Состояние успеха...
 */
data class Success(val labels: List<Label>) : LabelsListUiState
// [END_ANCHOR:Success]
```

### 4. Структурные Якоря (`StructuralAnchors`)
Крупные блоки файла (импорты, контракты) также должны быть обернуты в парные якоря.

*   `// [IMPORTS]` ... `// [END_IMPORTS]`
*   `// [CONTRACT]` ... `// [END_CONTRACT]`

### 5. Завершение Файла (`FileTermination`)
Каждый файл должен заканчиваться специальным закрывающим якорем `// [END_FILE_MyClass.kt]`.

### 6. Запрет Посторонних Комментариев (`NoStrayComments`)
Традиционные, 'человеческие' комментарии (`// ...` или `/* ... */`) **КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ**. Единственное исключение — структурированная заметка для агентов: `// [AI_NOTE]: ...`

---

## Принципы Проектирования

### A. Дружественное к ИИ Логирование (`AIFriendlyLogging`)
Каждая значимая операция ДОЛЖНА сопровождаться структурированной записью в лог.
*   **Формат:** `[LEVEL][ANCHOR][STATE]...`
*   **Ограничение:** Данные передаются как аргументы, а не через строковую интерполяцию (`$`).

### B. Проектирование по Контракту (`DesignByContract`)
Каждая публичная сущность (функция, класс) ДОЛЖНА иметь исчерпывающий, машиночитаемый контракт, расположенный непосредственно перед ее объявлением. Контракт заключается в якоря `[CONTRACT]` и `[END_CONTRACT]`.

**Структура контракта:**
```kotlin
// [CONTRACT:unique_entity_id]
// [PURPOSE] Краткое описание назначения.
// [PRE] Предусловие 1 (например, "входной список не пуст").
// [POST] Постусловие 1 (например, "возвращаемое значение не null").
// [PARAM:name:type] Описание параметра.
// [RETURN:type] Описание возвращаемого значения.
// [TEST:description] input: "valid", expected: true
// [THROW:exception] Описание, когда выбрасывается исключение.
// [END_CONTRACT:unique_entity_id]
```

**Реализация в коде:**
Предусловия и постусловия (`[PRE]` и `[POST]`), описанные в контракте, ДОЛЖНЫ быть реализованы в коде с использованием функций `require()` и `check()`.

### C. Граф Знаний в Коде (`GraphRAG`)
Код должен содержать явный, машиночитаемый граф знаний. Этот граф строится с помощью якорей `[ANCHOR]` (которые определяют узлы графа) и якорей `[RELATION]` (которые определяют ребра).

**Синтаксис триплета:**
Отношение (триплет "субъект-предикат-объект") определяется внутри якоря субъекта с помощью следующего синтаксиса:
`// [RELATION:predicate:object_id]`

*   **Субъект:** Неявно определяется якорем `[ANCHOR]`, в котором находится `[RELATION]`.
*   **Предикат:** Тип отношения из предопределенного списка.
*   **Объект:** `id` другого якоря `[ANCHOR]`.

**Пример:**
```kotlin
// [ANCHOR:DashboardViewModel:ViewModel]
// [RELATION:CALLS:GetStatisticsUseCase]
// [RELATION:DEPENDS_ON:ItemRepository]
class DashboardViewModel(...) { ... }
// [END_ANCHOR:DashboardViewModel]
```

**Таксономия:**
*   **Типы сущностей (для `[ANCHOR:id:type]`):** `Module`, `Class`, `Interface`, `Object`, `DataClass`, `SealedInterface`, `EnumClass`, `Function`, `UseCase`, `ViewModel`, `Repository`, `DataStructure`, `DatabaseTable`, `ApiEndpoint`.
*   **Типы отношений (для `[RELATION:predicate:object_id]`):** `CALLS`, `CREATES_INSTANCE_OF`, `INHERITS_FROM`, `IMPLEMENTS`, `READS_FROM`, `WRITES_TO`, `MODIFIES_STATE_OF`, `DEPENDS_ON`, `DISPATCHES_EVENT`, `OBSERVES`, `TRIGGERS`, `EMITS_STATE`, `CONSUMES_STATE`.