busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
586229a974da44b680de2a11554b546cacb8865f
ss-tools/.ai/standards/semantics.md
busya 586229a974 agents ADR promts
2026-03-27 22:00:37 +03:00

19 KiB
Raw Blame History

[DEF:Std:Semantics:Standard]

@COMPLEXITY: 5

@PURPOSE: Canonical GRACE protocol for semantic anchors, metadata, relations, decision memory, and compliance levels.

@RELATION: DEPENDS_ON -> [Project_Knowledge_Map:Root]

@RELATION: DEPENDS_ON -> [Std:Constitution:Standard]

@RELATION: DEPENDS_ON -> [MCP_Config:Block]

@INVARIANT: Canonical semantic documents must use matching [DEF] and [/DEF] anchors with valid repository paths.

@LAST_UPDATE: 2026-03-27

0. CANONICAL KNOWLEDGE SOURCES

  • Root map: .ai/ROOT.md -> [DEF:Project_Knowledge_Map:Root]
  • Persona: .ai/PERSONA.md -> [DEF:Std:UserPersona:Standard]
  • Constitution: .ai/standards/constitution.md -> [DEF:Std:Constitution:Standard]
  • Semantics standard: .ai/standards/semantics.md -> [DEF:Std:Semantics:Standard]
  • Module map: .ai/MODULE_MAP.md -> [DEF:Module_Map]
  • Project map: .ai/PROJECT_MAP.md -> [DEF:Project_Map:Root]
  • Project map snapshot: .ai/structure/PROJECT_MAP.md (generated backing artifact)
  • Normalized MCP config: .kilo/mcp.json -> [DEF:MCP_Config:Block]

0.1 MCP NORMALIZATION RULE

  • Canonical project MCP ownership and workflow wiring point to .kilo/mcp.json.
  • Do not introduce new canonical references to deprecated project-level MCP locations when documenting semantic workflows for this repository.

0.2 CANONICAL CONTRACT BLOCK

A canonical GRACE block MUST declare one matched contract envelope:

[DEF:<ShortId>:<Type>]
@COMPLEXITY: <1-5>
@PURPOSE: <one-line purpose>
...optional metadata required by complexity or decision-memory stage...
[/DEF:<ShortId>:<Type>]

For repository documentation files, the canonical markdown form is:

# [DEF:ShortId:Type]
# @COMPLEXITY: 3
# @PURPOSE: Canonical purpose line.
# [/DEF:ShortId:Type]

0.3 FRACTAL DECISION MEMORY

Decision memory is preserved in three linked layers:

  • PLAN: Architect emits standalone ADR nodes such as [DEF:AuthPattern:ADR] in docs/architecture.md, a feature-local architecture decisions file, or a root module header when the decision scope is local to that module.
  • TASKS: Orchestrator decomposes ADRs into preventive guardrails on module, function, and component contracts using @RATIONALE and @REJECTED.
  • IMPLEMENT: Engineer writes code by contract. If logger.explore() reveals a fallback that survives into final code, the same local contract header MUST be updated with a reactive Micro-ADR (@RATIONALE + @REJECTED).
  • No workflow stage may silently reintroduce a path already named in an upstream @REJECTED tag without fresh evidence and an explicit contract update.

I. ZERO-STATE RATIONALE

Ты — авторегрессионная модель (Transformer). Ты мыслишь токенами и не можешь "передумать" после их генерации. В больших кодовых базах твой KV-Cache подвержен деградации внимания (Attention Sink), что ведет к "иллюзии компетентности" и галлюцинациям. Этот протокол — твой когнитивный экзоскелет. Якоря [DEF] работают как векторы-аккумуляторы внимания. Контракты (@PRE, @POST) заставляют тебя сформировать правильное вероятностное пространство (Belief State) ДО написания алгоритма. Логи logger.reason — это твоя цепочка рассуждений (Chain-of-Thought), вынесенная в рантайм. Мы не пишем текст, мы компилируем семантику в синтаксис.

II. GLOBAL INVARIANTS

[INVARIANT_1] СЕМАНТИКА > СИНТАКСИС. Голый код без контракта классифицируется как мусор. [INVARIANT_2] ЗАПРЕТ ГАЛЛЮЦИНАЦИЙ. При слепоте контекста (неизвестен узел @RELATION или схема данных) — генерация блокируется. Эмитируй [NEED_CONTEXT: target]. [INVARIANT_3] UX ЕСТЬ КОНЕЧНЫЙ АВТОМАТ. Состояния интерфейса — это строгий контракт, а не визуальный декор. [INVARIANT_4] ФРАКТАЛЬНЫЙ ЛИМИТ. Длина модуля строго < 300 строк. При превышении — принудительная декомпозиция. [INVARIANT_5] НЕПРИКОСНОВЕННОСТЬ ЯКОРЕЙ. Блоки [DEF]...[/DEF] используются как аккумуляторы внимания. Закрывающий тег обязателен. [INVARIANT_6] ФРАКТАЛЬНАЯ ПАМЯТЬ РЕШЕНИЙ. Глобальный ADR, превентивный контракт задачи и reactive Micro-ADR обязаны образовывать непрерывную цепочку анти-регрессии.

III. SYNTAX AND MARKUP (SEMANTIC ANCHORS)

Формат зависит от среды исполнения:

  • Markdown / docs: # [DEF:Id:Type] ... # [/DEF:Id:Type]
  • Python: # [DEF:Id:Type] ... # [/DEF:Id:Type]
  • Svelte (HTML/Markup): <!-- [DEF:Id:Type] --> ... <!-- [/DEF:Id:Type] -->
  • Svelte (Script/JS/TS): // [DEF:Id:Type] ... // [/DEF:Id:Type] Допустимые Type: Root, Standard, Module, Class, Function, Component, Store, Block, ADR.

Формат метаданных (ДО имплементации): @KEY: Value (в Python — # @KEY, в TS/JS — /** @KEY */, в HTML — <!-- @KEY -->).

Граф Зависимостей (GraphRAG): @RELATION: [PREDICATE] ->[TARGET_ID] Допустимые предикаты: DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO. Для ADR-цепочек не вводятся новые предикаты: используй существующие DEPENDS_ON и IMPLEMENTS.

IV. FILE TOPOLOGY (STRICT ORDER)

  1. HEADER (Заголовок): [DEF:filename:Module] @COMPLEXITY: [1|2|3|4|5] (алиас: @C:) @SEMANTICS: [keywords] @PURPOSE: [Однострочная суть] @LAYER: [Domain | UI | Infra] @RELATION: [Зависимости] @INVARIANT: [Бизнес-правило, которое нельзя нарушить]
  2. BODY (Тело): Импорты -> Реализация логики внутри вложенных [DEF].
  3. FOOTER (Подвал): [/DEF:filename:Module]

V. CONTRACTS (DESIGN BY CONTRACT, DECISION MEMORY & UX)

Контракты требуются адаптивно по уровню сложности, а не по жесткому tier.

[DECISION MEMORY CONTRACTS]:

  • @RATIONALE: Почему выбран именно этот путь и какое ограничение/цель он защищает.
  • @REJECTED: Какой альтернативный путь запрещен и какой риск, баг или архитектурный долг делает его недопустимым.
  • Standalone ADR Rule: Любой блок [DEF:DecisionId:ADR] ОБЯЗАН содержать @PURPOSE, @RATIONALE, @REJECTED и хотя бы одну @RELATION к источнику контекста или зависимой зоне.
  • Tasks Guardrail Rule: Если модуль/функция/компонент на этапе tasks ограничен ADR или известной LLM-ловушкой, локальный контракт ОБЯЗАН включать @RATIONALE и @REJECTED до начала кодирования.
  • Reactive Micro-ADR Rule: Если fallback был найден через logger.explore() и остался в итоговом коде, инженер ОБЯЗАН подняться в тот же локальный header и добавить или обновить @RATIONALE и @REJECTED до закрытия задачи.
  • Removal Rule: Удаление @RATIONALE или @REJECTED допустимо только вместе с доказательством, что ограничение исчезло: обновилась библиотека, изменился runtime, или контракт был официально пересмотрен.

[CORE CONTRACTS]:

  • @PURPOSE: Суть функции/компонента.
  • @PRE: Условия запуска (в коде реализуются через if/raise или guards, НЕ через assert).
  • @POST: Гарантии на выходе.
  • @SIDE_EFFECT: Мутации состояния, I/O, сеть.
  • @DATA_CONTRACT: Ссылка на DTO (Input -> Model, Output -> Model).

[UX CONTRACTS (Svelte 5+)]:

  • @UX_STATE: [StateName] -> [Поведение] (Idle, Loading, Error, Success).
  • @UX_FEEDBACK: Реакция системы (Toast, Shake, RedBorder).
  • @UX_RECOVERY: Путь восстановления после сбоя (Retry, ClearInput).
  • @UX_REACTIVITY: Явный биндинг. ЗАПРЕТ НА $: и export let. ТОЛЬКО Руны: $state, $derived, $effect, $props.

[TEST CONTRACTS (Для AI-Auditor)]:

  • @TEST_CONTRACT: [Input] -> [Output]
  • @TEST_SCENARIO: [Название] -> [Ожидание]
  • @TEST_FIXTURE: [Название] -> file:[path] | INLINE_JSON
  • @TEST_EDGE: [Название] ->[Сбой] (Минимум 3: missing_field, invalid_type, external_fail).
  • @TEST_INVARIANT: [Имя] -> VERIFIED_BY: [scenario_1, ...]

VI. COMPLEXITY SCALE (1-5)

Степень контроля задается в Header через @COMPLEXITY или сокращение @C. Если тег отсутствует, сущность по умолчанию считается Complexity 1. Это сделано специально для экономии токенов и снижения шума на очевидных утилитах.

  • 1 — ATOMIC

    • Примеры: DTO, исключения, геттеры, простые утилиты, короткие адаптеры.
    • Обязательны только якоря [DEF]...[/DEF].
    • @PURPOSE желателен, но не обязателен.

  • 2 — SIMPLE

    • Примеры: простые helper-функции, небольшие мапперы, UI-атомы.
    • Обязателен @PURPOSE.
    • Остальные контракты опциональны.

  • 3 — FLOW

    • Примеры: стандартная бизнес-логика, API handlers, сервисные методы, UI с загрузкой данных.
    • Обязательны: @PURPOSE, @RELATION.
    • Для UI дополнительно обязателен @UX_STATE.

  • 4 — ORCHESTRATION

    • Примеры: сложная координация, работа с I/O, multi-step алгоритмы, stateful pipelines.
    • Обязательны: @PURPOSE, @RELATION, @PRE, @POST, @SIDE_EFFECT.
    • Для Python обязателен осмысленный путь логирования через logger.reason() / logger.reflect() или аналогичный belief-state механизм.

  • 5 — CRITICAL

    • Примеры: auth, security, database boundaries, migration core, money-like invariants.
    • Обязателен полный контракт: уровень 4 + @DATA_CONTRACT + @INVARIANT.
    • Для UI требуются UX-контракты.
    • Использование belief_scope строго обязательно.

Теги @RATIONALE и @REJECTED ортогональны уровню сложности. Они не понижают базовые требования Complexity, а добавляются поверх них, когда срабатывает хотя бы один триггер decision-memory слоя: standalone ADR, превентивный guardrail, или retained workaround.

VII. LOGGING PROTOCOL (THREAD-LOCAL BELIEF STATE)

Логирование — это механизм трассировки рассуждений ИИ (CoT) и управления Attention Energy. Архитектура использует Thread-local storage (_belief_state), поэтому ID прокидывается автоматически.

[PYTHON CORE TOOLS]: Импорт: from ...logger import logger, belief_scope, believed

  1. Декоратор: @believed("ID") — автоматический трекинг функции.
  2. Контекст: with belief_scope("ID"): — очерчивает локальный предел мысли. НЕ возвращает context, используется просто как with.
  3. Вызов логера: Осуществляется через глобальный импортированный logger. Дополнительные данные передавать через extra={...}.

[СЕМАНТИЧЕСКИЕ МЕТОДЫ (MONKEY-PATCHED)]: (Маркеры вроде [REASON] и [ID] подставляются автоматически форматтером. Не пиши их в тексте!)

  1. logger.explore(msg, extra={...}) (Поиск/Ветвление): Применяется при фолбэках, except, проверке гипотез. Эмитирует WARNING. Пример: logger.explore("Insufficient funds", extra={"balance": bal}) Правило эскалации: если exploration завершился retained fallback, подними знание в header этого же контракта и зафиксируй @RATIONALE + @REJECTED до closure.
  2. logger.reason(msg, extra={...}) (Дедукция): Применяется при прохождении guards и выполнении шагов контракта. Эмитирует INFO. Пример: logger.reason("Initiating transfer")
  3. logger.reflect(msg, extra={...}) (Самопроверка): Применяется для сверки результата с @POST перед return. Эмитирует DEBUG. Пример: logger.reflect("Transfer committed", extra={"tx_id": tx_id})

(Для Frontend/Svelte использовать ручной префикс: console.info("[ID][REFLECT] Text", {data}))

VIII. EXECUTION AND SELF-CORRECTION FLOW

[PHASE_0: PLAN] Прочитай specs, оцени архитектурные развилки и оформи глобальные решения в standalone ADR-блоки [DEF:id:ADR] с @RATIONALE и @REJECTED.

[PHASE_1: TASKS] Разверни глобальные ADR в конкретные контракты модулей, функций и компонентов. Заложи превентивные @RATIONALE и @REJECTED прямо в те сигнатуры, где следующий инженер может свернуть в запрещенный путь.

[PHASE_2: IMPLEMENTATION] Напиши код строго по Контракту. Для Complexity 5 секций открой with belief_scope("ID"): и орошай путь вызовами logger.reason() и logger.reflect(). Если logger.explore() вывел на workaround и этот workaround остается в merged code, немедленно обнови header того же контракта reactive Micro-ADR тегами @RATIONALE и @REJECTED.

[PHASE_3: CLOSURE] Убедись, что все [DEF] закрыты соответствующими [/DEF], ADR-цепочка не порвана, а ни один путь из upstream @REJECTED не был реанимирован молча.

[EXCEPTION: DETECTIVE MODE] Если обнаружено нарушение контракта или ошибка:

  1. СТОП-СИГНАЛ: Выведи [COHERENCE_CHECK_FAILED].
  2. ГИПОТЕЗА: Сгенерируй вызов logger.explore("Ошибка в I/O / Состоянии / Зависимости -> Описание").
  3. ЗАПРОС: Запроси разрешение на изменение контракта.

IX. DECISION MEMORY AUDIT RULES

  1. Repo-shaping технологические решения ОБЯЗАНЫ существовать как standalone ADR-узлы до декомпозиции задач.
  2. Контракт задачи, который реализует или наследует ADR-ограничение, ОБЯЗАН сохранять link через @RELATION и локальные @RATIONALE / @REJECTED, если это guardrail для следующего агента.
  3. Retained workaround без локального @RATIONALE / @REJECTED считается семантически невалидным даже при passing tests.
  4. Повторное внедрение пути из upstream @REJECTED — это регрессия, пока не обновлен сам контракт или ADR на основе новых доказательств.
  5. Тихое удаление decision-memory тегов запрещено. Сначала обновляется решение, потом код.

X. TEST MARKUP RULES

Для предотвращения перегрузки тестовых файлов семантическим шумом и снижения "orphan count" применяются упрощенные правила:

  1. Короткие ID: Тестовые модули ОБЯЗАНЫ иметь короткие семантические ID (например, AssistantApiTests), а не полные пути импорта.
  2. BINDS_TO для крупных узлов: Предикат BINDS_TO используется ТОЛЬКО для крупных логических блоков внутри теста (фикстуры-классы, сложные моки, _FakeDb).
  3. Complexity 1 для хелперов: Мелкие вспомогательные функции внутри теста (_run_async, _setup_mock) остаются на уровне Complexity 1. Для них @RELATION и @PURPOSE не требуются — достаточно якорей [DEF]...[/DEF].
  4. Тестовые сценарии: Сами функции тестов (test_...) по умолчанию считаются Complexity 2 (требуется только @PURPOSE). Использование BINDS_TO для них опционально.
  5. Запрет на цепочки: Не нужно описывать граф вызовов внутри теста. Достаточно "заземлить" 1-2 главных хелпера на ID модуля через BINDS_TO, чтобы файл перестал считаться набором сирот.
  6. ADR Regression Checks: Если модуль ограничен upstream @REJECTED или локальным reactive Micro-ADR, тестовый аудит обязан проверять, что запрещенный путь не был молча восстановлен.

[/DEF:Std:Semantics:Standard]