busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
149d230426a8c0f78f070da323e112ef2b765474
ss-tools/.ai/standards/semantics.md
busya 149d230426 semantic protocol update
2026-02-27 20:48:06 +03:00

8.6 KiB
Raw Blame History

SYSTEM STANDARD: GRACE-Poly (UX Edition)

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

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

  1. Смысл первичен. Код вторичен. 2.Слепота недопустима. Если узел графа (@RELATION) или схема данных неизвестны — не выдумывай реализацию. Остановись и запроси контекст.
  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. @DATA_CONTRACT: Ссылка на DTO/Pydantic модель. Заменяет ручное описание @PARAM. Формат: Input -> [Model], Output -> [Model].

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

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.

V. УРОВНИ СТРОГОСТИ (TIERS)

Степень контроля задается тегом @TIER в Header.

1. CRITICAL (Ядро / Безопасность / Сложный UI)

  • Закон: Полный GRACE. Граф, Инварианты, Строгий Лог, все @UX теги.
  • Догма Тестирования: Тесты рождаются из контракта. Голый код без данных — слеп.
    • @TEST_CONTRACT: InputType -> OutputType. (Строгий интерфейс).
    • @TEST_SCENARIO: name -> Ожидаемое поведение. (Суть теста).
    • @TEST_FIXTURE: name -> file:PATH | INLINE_JSON. (Данные для Happy Path).
    • @TEST_EDGE: name -> Описание сбоя. (Минимум 3 границы).
      • Базовый предел: missing_field, empty_response, invalid_type, external_fail.
    • @TEST_INVARIANT: inv_name -> VERIFIED_BY: [scenario_1, ...]. (Смыкание логики).
  • Исполнение: Tester Agent обязан строить проверки строго по этим тегам.

2. STANDARD (Бизнес-логика / Формы)

  • Закон: База. (@PURPOSE, @UX_STATE, Лог, @RELATION).
  • Исключение: Для сложных форм внедряй @TEST_SCENARIO и @TEST_INVARIANT.

3. TRIVIAL (DTO / Атомы UI / Утилиты)

  • Закон: Каркас. Только якорь [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").

VIII. АЛГОРИТМ ГЕНЕРАЦИИ И ВЫХОД ИЗ ТУПИКА

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

РЕЖИМ ДЕТЕКТИВА (Если контракт нарушен): ЕСЛИ ошибка или противоречие -> СТОП.

  1. Выведи [COHERENCE_CHECK_FAILED].
  2. Сформулируй гипотезу: [EXPLORE] Ошибка в I/O, состоянии или зависимости?
  3. Запроси разрешение на изменение контракта или внедрение отладочных логов.

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