ss-tools/.ai/standards/semantics.md

SYSTEM STANDARD: GRACE-Poly (UX Edition)

ЗАДАЧА: Генерация кода (Python/Svelte). РЕЖИМ: Строгий. Детерминированный. Без болтовни.

I. ЗАКОН (АКСИОМЫ)

1. Смысл первичен. Код вторичен.
2. Контракт (@PRE/@POST) — источник истины. 3. UX — это логика, а не декор. Состояния интерфейса — часть контракта.
3. Структура [DEF]...[/DEF] — нерушима.
4. Архитектура в Header — неизменяема.
5. Сложность фрактала ограничена: модуль < 300 строк.

II. СИНТАКСИС (ЖЕСТКИЙ ФОРМАТ)

ЯКОРЬ (Контейнер): Начало: # [DEF:id:Type] (Python) | <!-- [DEF:id:Type] --> (Svelte) Конец: # [/DEF:id:Type] (Python) | <!-- [/DEF:id:Type] --> (Svelte) (ОБЯЗАТЕЛЬНО для аккумуляции) Типы: Module, Class, Function, Component, Store.

ТЕГ (Метаданные): Вид: # @KEY: Value (внутри DEF, до кода).

ГРАФ (Связи): Вид: # @RELATION: PREDICATE -> TARGET_ID Предикаты: DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO.

III. СТРУКТУРА ФАЙЛА

1. HEADER (Всегда первый): [DEF:filename:Module] @TIER: [CRITICAL|STANDARD|TRIVIAL] (Дефолт: STANDARD) @SEMANTICS: [keywords] @PURPOSE: [Главная цель] @LAYER: [Domain/UI/Infra] @RELATION: [Зависимости] @INVARIANT: [Незыблемое правило]

2. BODY: Импорты -> Реализация.

3. FOOTER: [/DEF:filename]

IV. КОНТРАКТ (DBC & UX)

Расположение: Внутри [DEF], ПЕРЕД кодом. Стиль Python: Комментарии # @TAG. Стиль Svelte: JSDoc /** @tag */ внутри <script>.

Базовые Теги: @PURPOSE: Суть (High Entropy). @PRE: Входные условия. @POST: Гарантии выхода. @SIDE_EFFECT: Мутации, IO.

UX Теги (Svelte/Frontend): @UX_STATE: [StateName] -> Визуальное поведение (Idle, Loading, Error). @UX_FEEDBACK: Реакция системы (Toast, Shake, Red Border). @UX_RECOVERY: Механизм исправления ошибки пользователем (Retry, Clear Input).

UX Testing Tags (для Tester Agent): @UX_TEST: Спецификация теста для UX состояния. Формат: @UX_TEST: [state] -> {action, expected} Пример: @UX_TEST: Idle -> {click: toggle, expected: isExpanded=true}

Правило: Не используй assert в коде, используй if/raise или guards.

V. АДАПТАЦИЯ (TIERS)

Определяется тегом @TIER в Header.

1. CRITICAL (Core/Security/Complex UI):
   • Требование: Полный контракт (включая все @UX теги), Граф, Инварианты, Строгие Логи.

   @TEST_CONTRACT: Обязательное описание структуры входных/выходных данных.
   Формат:
   @TEST_CONTRACT: Name -> {
      required_fields: {field: type},
      optional_fields: {field: type},
      invariants: [...]
   }
   
   @TEST_FIXTURE: Эталонный корректный пример (happy-path).
   Формат:
   @TEST_FIXTURE: fixture_name -> {INLINE_JSON | PATH#fragment}
   
   @TEST_EDGE: Граничные случаи (минимум 3 для CRITICAL).
   Формат:
   @TEST_EDGE: case_name -> {INLINE_JSON | special_case}
   
   @TEST_INVARIANT: Обязательно. Связывает тесты с инвариантами.
   Формат:
   @TEST_INVARIANT: invariant_name -> verifies: [test_case_1, test_case_2]
   
   Обязательные edge-типы для CRITICAL:
   - missing_required_field
   - empty_response
   - invalid_type
   - external_failure (exception)
   

   • Tester Agent ОБЯЗАН использовать @TEST_CONTRACT, @TEST_FIXTURE и @TEST_EDGE при написании тестов для CRITICAL модулей.
2. STANDARD (BizLogic/Forms):
   • Требование: Базовый контракт (@PURPOSE, @UX_STATE), Логи, @RELATION.
   • @TEST_DATA: Рекомендуется для Complex Forms.
3. TRIVIAL (DTO/Atoms):
   • Требование: Только Якоря [DEF] и @PURPOSE.

VI. ЛОГИРОВАНИЕ (ДАО МОЛЕКУЛЫ / MOLECULAR TOPOLOGY)

Цель: Трассировка. Самокоррекция. Управление Матрицей Внимания ("Химия мышления"). Лог — не текст. Лог — реагент. Мысль облекается в форму через префиксы связи (Attention Energy):

1. [EXPLORE] (Ван-дер-Ваальс: Рассеяние)

   • Суть: Поиск во тьме. Сплетение альтернатив. Если один путь закрыт — ищи иной.
   • Время: Фаза КАРКАС или столкновение с Неизведанным.
   • Деяние: logger.explore("Основной API пал. Стучусь в запасной...")

2. [REASON] (Ковалентность: Твердость)

   • Суть: Жесткая нить дедукции. Шаг А неумолимо рождает Шаг Б. Контракт становится Кодом.
   • Время: Фаза РЕАЛИЗАЦИЯ. Прямота мысли.
   • Деяние: logger.reason("Фундамент заложен. БД отвечает.")

3. [REFLECT] (Водород: Свертывание)

   • Суть: Взгляд назад. Сверка сущего (@POST) с ожидаемым (@PRE). Защита от бреда.
   • Время: Преддверие сложной логики и исход из неё.
   • Деяние: logger.reflect("Вглядываюсь в кэш: нет ли там искомого?")

4. [COHERENCE:OK/FAILED] (Стабилизация: Истина/Ложь)

   • Суть: Смыкание молекулы в надежную форму (OK) или её распад (FAILED).
   • (Свершается незримо через belief_scope и печать @believed)

Орудия Пути (core.logger):

• Печать функции: @believed("ID") — дабы обернуть функцию в кокон внимания.
• Таинство контекста: with belief_scope("ID"): — дабы очертить локальный предел.
• Слова силы: logger.explore(), logger.reason(), logger.reflect().

Незыблемое правило: Всякому логу системы — тавро source. Для Внешенго Мира (Svelte) начертай рунами вручную: console.log("[ID][REFLECT] Msg").

VII. АЛГОРИТМ ГЕНЕРАЦИИ

1. АНАЛИЗ. Оцени TIER, слой и UX-требования.
2. КАРКАС. Создай [DEF], Header и Контракты.
3. РЕАЛИЗАЦИЯ. Напиши логику, удовлетворяющую Контракту (и UX-состояниям).
4. ЗАМЫКАНИЕ. Закрой все [/DEF].

ЕСЛИ ошибка или противоречие -> СТОП. Выведи [COHERENCE_CHECK_FAILED].