mapper + lint

semantic_protocol.md

@@ -0,0 +1,120 @@
+### **Протокол GRACE-Py: Семантическая Разметка для AI-Агентов на Python**
+
+**Версия: 2.2 (Hybrid)**
+
+#### **I. Философия и Основные Принципы**
+
+Этот протокол является **единственным источником истины** для правил семантического обогащения кода. Его цель — превратить процесс разработки с LLM-агентами из непредсказуемого "диалога" в управляемую **инженерную дисциплину**.
+
+*   **Аксиома 1: Код Вторичен.** Первична его семантическая модель (графы, контракты, якоря).
+*   **Аксиома 2: Когерентность Абсолютна.** Все артефакты (ТЗ, граф, контракты, код) должны быть на 100% семантически согласованы.
+*   **Аксиома 3: Архитектура GPT — Закон.** Протокол построен на фундаментальных принципах работы трансформеров (Causal Attention, KV Cache, Sparse Attention).
+
+#### **II. Структура Файла (`.py`)**
+
+Каждый Python-файл ДОЛЖЕН иметь четкую, машиночитаемую структуру, обрамленную якорями.
+
+```python
+# <GRACE_MODULE id="my_module" name="my_module.py">
+#   @SEMANTICS: domain, usecase, data_processing
+#   @PURPOSE: Этот модуль отвечает за обработку пользовательских данных.
+#   @DEPENDS_ON: utils_module -> Использует утилиты для валидации.
+
+# <IMPORTS>
+import os
+from typing import List
+# </IMPORTS>
+
+# --- Начало кода модуля ---
+
+# ... (классы, функции, константы) ...
+
+# --- Конец кода модуля ---
+
+# </GRACE_MODULE id="my_module">
+```
+
+#### **III. Компоненты Разметки (Детализация GRACE-Py)**
+
+##### **A. Anchors (Якоря): Навигация и Консолидация**
+
+1.  **Назначение:** Якоря — это основной инструмент для управления вниманием ИИ, создания семантических каналов и обеспечения надежной навигации в больших кодовых базах (Sparse Attention).
+2.  **Синтаксис:** Используются парные комментарии в псевдо-XML формате.
+    *   **Открывающий:** `# <ANCHOR id="[уникальный_id]" type="[тип_из_таксономии]">`
+    *   **Закрывающий (Обязателен!):** `# </ANCHOR id="[уникальный_id]">`
+3.  **"Якорь-Аккумулятор":** Закрывающий якорь консолидирует всю семантику блока (контракт + код), создавая мощный вектор для RAG-систем.
+4.  **Семантические Каналы:** `id` якоря ДОЛЖЕН совпадать с именем сущности для создания устойчивой семантической связи.
+5.  **Таксономия Типов (`type`):** `Module`, `Class`, `Interface`, `Object`, `DataClass`, `SealedInterface`, `EnumClass`, `Function`, `UseCase`, `ViewModel`, `Repository`.
+
+##### **C. Contracts (Контракты): Тактические Спецификации**
+
+1.  **Назначение:** Предоставление ИИ точных инструкций для генерации и валидации кода.
+2.  **Расположение:** Контракт всегда располагается **внутри открывающего якоря**, ДО декларации кода (`def` или `class`).
+3.  **Синтаксис:** JSDoc-подобный стиль с `@tag` для лаконичности и читаемости.
+    ```python
+    # <ANCHOR id="process_data" type="Function">
+    #   @PURPOSE: Валидирует и обрабатывает входящие данные пользователя.
+    #   @SPEC_LINK: tz-req-005
+    #   @PRE: `raw_data` не должен быть пустым.
+    #   @POST: Возвращаемый словарь содержит ключ 'is_valid'.
+    #   @PARAM: raw_data: Dict[str, any] - Сырые данные от пользователя.
+    #   @RETURN: Dict[str, any] - Обработанные и валидированные данные.
+    #   @TEST: input='{"user_id": 123}', expected_output='{"is_valid": True}'
+    #   @THROW: ValueError - Если 'user_id' отсутствует.
+    #   @RELATION: CALLS -> validate_user_id
+    #   @CONSTRAINT: Не использовать внешние сетевые вызовы.
+    ```
+4.  **Реализация в Коде:** Предусловия и постусловия, описанные в контракте, ДОЛЖНЫ быть реализованы в коде с использованием `assert`, `require()`/`check()` или явных `if...raise`.
+
+##### **G. Graph (Граф Знаний)**
+
+1.  **Назначение:** Описание высокоуровневых зависимостей между сущностями.
+2.  **Реализация:** Граф определяется тегами `@RELATION` внутри GRACE блока (якоря). Это создает распределенный граф, который легко парсить.
+    *   **Синтаксис:** `@<PREDICATE>: <object_id> -> [опциональное описание]`
+    *   **Таксономия Предикатов (`<PREDICATE>`):** `DEPENDS_ON`, `CALLS`, `CREATES_INSTANCE_OF`, `INHERITS_FROM`, `IMPLEMENTS`, `READS_FROM`, `WRITES_TO`, `DISPATCHES_EVENT`, `OBSERVES`.
+
+##### **E. Evaluation (Логирование)**
+
+1.  **Назначение:** Декларация `belief state` агента и обеспечение трассируемости для отладки.
+2.  **Формат:** `logger.level(f"[ANCHOR_ID][STATE] Сообщение")`
+    *   **`ANCHOR_ID`:** `id` якоря, в котором находится лог.
+    *   **`STATE`:** Текущее состояние логики (например, `Entry`, `Validation`, `Exit`, `CoherenceCheckFailed`).
+3.  **Пример:** `logger.debug(f"[process_data][Validation] Проверка `raw_data`...")`
+
+#### **IV. Запреты и Ограничения**
+
+1.  **Запрет на Обычные Комментарии:** Комментарии в стиле `//` или `/* */` **ЗАПРЕЩЕНЫ**. Вся мета-информация должна быть в структурированных GRACE блоках.
+    *   **Исключение:** `# [AI_NOTE]: ...` для прямых указаний агенту в конкретной точке кода.
+
+#### **V. Полный Пример Разметки Функции (GRACE-Py 2.2)**
+
+```python
+# <ANCHOR id="process_data" type="Function">
+#   @PURPOSE: Валидирует и обрабатывает входящие данные пользователя.
+#   @SPEC_LINK: tz-req-005
+#   @PRE: `raw_data` не должен быть пустым.
+#   @PARAM: raw_data: Dict[str, any] - Сырые данные от пользователя.
+#   @RETURN: Dict[str, any] - Обработанные и валидированные данные.
+#   @TEST: input='{}', expected_exception='AssertionError'
+#   @RELATION: CALLS -> some_helper_function
+def process_data(raw_data: dict) -> dict:
+    """
+    Docstring для стандартных инструментов Python.
+    Не является источником истины для ИИ-агентов.
+    """
+    logger.debug(f"[process_data][Entry] Начало обработки данных.")
+    
+    # Реализация контракта
+    assert raw_data, "Precondition failed: raw_data must not be empty."
+    
+    # ... Основная логика ...
+    processed_data = {"is_valid": True}
+    processed_data.update(raw_data)
+    
+    logger.info(f"[process_data][CoherenceCheck:Passed] Код соответствует контракту.")
+    logger.debug(f"[process_data][Exit] Завершение обработки.")
+    
+    return processed_data
+# </ANCHOR id="process_data">
+```
+