# 📋 ТЕХНИЧЕСКОЕ ЗАДАНИЕ: ИНТЕГРАЦИЯ MIXED-INITIATIVE LLM-АГЕНТА
**Ветка:** `027-dataset-llm-orchestration`
**Контекст:** Архитектура автоматического ревью датасетов (US1) и подготовки к запуску (US3) реализована отлично. Требуется переработать процесс "Clarification" (US2) из жесткого модального опросника в полноценный контекстно-зависимый диалог с LLM-агентом (Смешанная инициатива / Mixed-Initiative), а также закрыть архитектурные риски (PII, Concurrency).

Тебе необходимо выполнить задачу в два этапа.

---

## ЭТАП 1: Обновление спецификаций (Директория `specs/027-dataset-llm-orchestration/`)

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

**1. Обновить `ux_reference.md`:**
*   **Отказ от модалок:** Заменить концепцию `ClarificationDialog` на интеграцию диалога в выдвижную правую панель `AssistantChatPanel`.
*   **Mixed-Initiative:** Описать, что диалог может быть инициирован как системой (очередь `Clarification Queue`), так и пользователем (свободные вопросы агенту по контексту датасета, например: *"Почему этот фильтр помечен как partial?"*).
*   **Inline-взаимодействие (Context Actions):** Дописать появление микро-кнопок `[✨ Спросить ИИ]` / `[✨ Улучшить]` рядом с неразрешенными фильтрами (`unresolved`), предупреждениями валидации и полем Бизнес-summary в основном Workspace.
*   **Визуальный фокус:** Зафиксировать правило: когда агент задает вопрос по конкретному фильтру/полю в чате, карточка этого элемента в центральной колонке UI подсвечивается (highlight/glow).
*   **Confirmation Cards:** Описать интерактивные виджеты внутри ленты чата для опасных операций (например, подтверждение запуска датасета в SQL Lab), опирающиеся на `AssistantConfirmationRecord`.

**2. Обновить `spec.md` (Functional Requirements):**
*   Добавить **FR-045**: Система должна позволять пользователю задавать свободные вопросы по контексту загруженного датасета (профиль, фильтры, маппинги, SQL).
*   Добавить **FR-046**: Агент должен уметь принимать команды на естественном языке для изменения состояния сессии (например: *"Одобри все маппинги"*, *"Сгенерируй превью SQL"*).
*   Изменить **FR-013**: Уточняющие вопросы должны задаваться не в изолированном окне, а в контексте глобального чата ассистента.

**3. Обновить `contracts/api.yaml` и `data-model.md`:**
*   **Связь чата и сессии:** В `AssistantMessageRequest` добавить опциональное поле `dataset_review_session_id: string`.
*   **Оптимистичные блокировки:** В сущность `DatasetReviewSession` (и DTO `SessionDetail`) добавить поле `version: integer` для предотвращения состояния гонки (Race Condition) при совместном редактировании сессии коллабораторами (пользователь + агент).
*   **PII Masking:** В `data-model.md` для `ImportedFilter` явно указать требование маскирования чувствительных данных (`raw_value`) перед отправкой контекста в LLM.

**4. Обновить `contracts/modules.md`:**
*   В `DatasetReviewOrchestrator` добавить связь `@RELATION: [EXPOSES_STATE_TO] -> [AssistantApi]`.
*   В описание `ClarificationEngine` добавить, что он маршрутизирует свои запросы через `AssistantChatPanel`.

---

## ЭТАП 2: Реализация доработок в кодовой базе (Frontend & Backend)

На основе обновленных спеков реализуй архитектурные и UI/UX изменения в коде.

### 🛠️ 2.1 Backend: Архитектура, Безопасность и Инструменты Агента
1.  **PII Data Masking:** 
    *   Где: `backend/src/core/utils/superset_context_extractor.py` или слой подготовки промпта.
    *   Что: Реализовать фильтрацию/маскирование значений фильтров (например, email, SSN), извлеченных из Superset, *до* того, как они попадут в контекст LLM. Агенту нужны только ключи и структура для маппинга, а не сырые PII-данные.
2.  **Optimistic Locking (Борьба с Race Conditions):**
    *   Где: `backend/src/services/dataset_review/repositories/session_repository.py`.
    *   Что: Реализовать проверку поля `version` при сохранении `DatasetReviewSession`. В случае конфликта (кто-то другой, включая агента, уже изменил сессию) выбрасывать `StaleDataError` -> HTTP 409 Conflict.
3.  **Интеграция контекста датасета в Ассистента:**
    *   Где: `backend/src/api/routes/assistant.py` (`_plan_intent_with_llm`, `_build_tool_catalog`).
    *   Что: Если в запросе передан `dataset_review_session_id`, подгружать `DatasetProfile`, `ImportedFilters` и `ValidationFindings` в системный промпт (System Prompt) ассистента, чтобы он мог отвечать на вопросы по датасету.
4.  **Новые Tools (Интенты) для Агента:**
    *   Где: `backend/src/api/routes/assistant.py` -> `_dispatch_intent`.
    *   Что: Научить агента вызывать методы `DatasetReviewOrchestrator`. Добавить инструменты: `APPROVE_MAPPINGS` (одобрить ворнинги), `SET_FIELD_SEMANTICS` (переписать описание колонки), `GENERATE_SQL_PREVIEW` (триггер компиляции).
5.  **Garbage Collection сессий:**
    *   Где: `backend/src/core/task_manager/cleanup.py` (или аналог).
    *   Что: Написать scheduled-таску для жесткого удаления (hard delete) брошенных/архивированных сессий обзора (например, старше 30 дней), чтобы БД не переполнялась снепшотами SQL и графами контекста.

### 🎨 2.2 Frontend: Реактивный Workspace и Чат
1.  **Интеграция AssistantChatPanel (Slide-out Drawer):**
    *   Где: `frontend/src/routes/datasets/review/[id]/+page.svelte` (`DatasetReviewWorkspace`).
    *   Что: Внедрить вызов боковой панели ассистента `AssistantChatPanel`. Убедиться, что при её открытии контент Workspace сдвигается или корректно перекрывается, не теряя контекста SQL-превью и фильтров. Удалить старый `ClarificationDialog` (модалку).
2.  **Контекстные кнопки (Inline Triggers ✨):**
    *   Что: В компоненты `ValidationFindingsPanel.svelte`, `ExecutionMappingReview.svelte` и карточки фильтров добавить микро-кнопки `[✨ Спросить ИИ]`.
    *   Действие: По клику открывать `assistantChat` store и отправлять предзаполненный скрытый контекстный промпт (например, *"Объясни проблему с фильтром X и предложи решение"*).
3.  **Визуальная синхронизация (State Reactivity):**
    *   Что: Когда агент через чат задает вопрос по `field_id` или `filter_id` (Clarification Queue), соответствующий элемент в Workspace должен получать CSS-класс подсветки (glow/highlight).
    *   Как: Связать `ClarificationStateResult` из стора сессии с рендером строк в `SemanticLayerReview.svelte` и списках фильтров.
4.  **Confirmation Cards в ленте чата:**
    *   Где: `frontend/src/lib/components/assistant/AssistantChatPanel.svelte`.
    *   Что: Для команд, требующих `AssistantConfirmationRecord` (например, запуск в SQL Lab), рендерить внутри чата специальный виджет: *"Вы уверены, что хотите запустить этот контекст? [Отменить][Запустить]"*.
5.  **Debounce для SQL Preview:**
    *   Где: `frontend/src/lib/components/dataset-review/CompiledSQLPreview.svelte`.
    *   Что: Предотвратить спам запросами к Superset API. Если пользователь или агент быстро меняют маппинги, статус превью становится `stale`. Запрос на перегенерацию должен отправляться либо по явной кнопке, либо с debounce-задержкой 2-3 секунды после окончания потока изменений.

### ⚙️ Правила выполнения для Агента:
1. **Не ломать инварианты:** Сохранить принцип **WYSIWWR (What You See Is What Will Run)**. LLM *никогда* не должна генерировать финальный SQL-код сама. LLM собирает параметры, а SQL компилирует только Superset (`SupersetCompilationAdapter`).
2. **Семантическое логирование:** Любые изменения состояния сессий на бэкенде оборачивать в `belief_scope` (`logger.reason()`, `logger.reflect()`), как указано в системных контрактах.
3. По завершении этапа 1, дождись утверждения (или переходи к Этапу 2 автономно, если находишься в режиме Auto-Execute), строго следуя обновленным контрактам `api.yaml`.