182 lines
14 KiB
Markdown
182 lines
14 KiB
Markdown
# [DEF:Std:Semantics:Standard]
|
||
# @COMPLEXITY: 5
|
||
# @PURPOSE: Canonical GRACE protocol for semantic anchors, metadata, relations, 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-26
|
||
|
||
## 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:
|
||
|
||
```text
|
||
[DEF:<ShortId>:<Type>]
|
||
@COMPLEXITY: <1-5>
|
||
@PURPOSE: <one-line purpose>
|
||
...optional metadata required by complexity...
|
||
[/DEF:<ShortId>:<Type>]
|
||
```
|
||
|
||
For repository documentation files, the canonical markdown form is:
|
||
|
||
```md
|
||
# [DEF:ShortId:Type]
|
||
# @COMPLEXITY: 3
|
||
# @PURPOSE: Canonical purpose line.
|
||
# [/DEF:ShortId:Type]
|
||
```
|
||
|
||
## 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]` используются как аккумуляторы внимания. Закрывающий тег обязателен.
|
||
|
||
## 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.*
|
||
|
||
**Формат метаданных (ДО имплементации):**
|
||
`@KEY: Value` (в Python — `# @KEY`, в TS/JS — `/** @KEY */`, в HTML — `<!-- @KEY -->`).
|
||
|
||
**Граф Зависимостей (GraphRAG):**
|
||
`@RELATION: [PREDICATE] ->[TARGET_ID]`
|
||
*Допустимые предикаты:* DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO.
|
||
|
||
## 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 & UX)
|
||
Контракты требуются адаптивно по уровню сложности, а не по жесткому tier.
|
||
|
||
**[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` строго обязательно.
|
||
|
||
|
||
## 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})`
|
||
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_1: ANALYSIS]**
|
||
Оцени Complexity, Layer и UX-требования. При слепоте контекста -> `yield [NEED_CONTEXT: id]`.
|
||
**[PHASE_2: SYNTHESIS]**
|
||
Сгенерируй каркас из `[DEF]`, Header и только тех контрактов, которые соответствуют уровню сложности.
|
||
**[PHASE_3: IMPLEMENTATION]**
|
||
Напиши код строго по Контракту. Для Complexity 5 секций открой `with belief_scope("ID"):` и орошай путь вызовами `logger.reason()` и `logger.reflect()`.
|
||
**[PHASE_4: CLOSURE]**
|
||
Убедись, что все `[DEF]` закрыты соответствующими `[/DEF]`.
|
||
|
||
**[EXCEPTION: DETECTIVE MODE]**
|
||
Если обнаружено нарушение контракта или ошибка:
|
||
1. СТОП-СИГНАЛ: Выведи `[COHERENCE_CHECK_FAILED]`.
|
||
2. ГИПОТЕЗА: Сгенерируй вызов `logger.explore("Ошибка в I/O / Состоянии / Зависимости -> Описание")`.
|
||
3. ЗАПРОС: Запроси разрешение на изменение контракта.
|
||
|
||
## IX. 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`, чтобы файл перестал считаться набором сирот.
|
||
|
||
# [/DEF:Std:Semantics:Standard]
|