refactor(semantics): migrate TIER system to adaptive COMPLEXITY 1-5 scale

- Replaced rigid TIERs with continuous COMPLEXITY 1-5 scale in semantics.md - Updated generate_semantic_map.py to parse and score based on Complexity - Added backward compatibility mapping for legacy TIERs - Migrated all .ai/shots examples to use @COMPLEXITY and updated relation syntax - Added trivial_utility.py shot to demonstrate implicit Complexity 1 token savings
2026-03-16 09:54:13 +03:00
parent 54e90b589b
commit 321e0eb2db
7 changed files with 236 additions and 124 deletions
--- a/.ai/shots/backend_route.py
+++ b/.ai/shots/backend_route.py
@@ -1,10 +1,9 @@
 #[DEF:BackendRouteShot:Module]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @SEMANTICS: Route, Task, API, Async
 # @PURPOSE: Reference implementation of a task-based route using GRACE-Poly.
 # @LAYER: Interface (API)
-# @RELATION: IMPLEMENTS -> [DEF:Std:API_FastAPI]
-# @INVARIANT: TaskManager must be available in dependency graph.
+# @RELATION: [IMPLEMENTS] ->[API_FastAPI]

 from typing import Dict, Any
 from fastapi import APIRouter, Depends, HTTPException, status
@@ -25,15 +24,13 @@ class CreateTaskRequest(BaseModel):
 # [/DEF:CreateTaskRequest:Class]

 # [DEF:create_task:Function]
+# @COMPLEXITY: 4
 # @PURPOSE: Create and start a new task using TaskManager. Non-blocking.
-# @DATA_CONTRACT: Input -> CreateTaskRequest, Output -> Task
+# @RELATION: [CALLS] ->[task_manager.create_task]
 # @PRE: plugin_id must match a registered plugin.
 # @POST: A new task is spawned; Task object returned immediately.
 # @SIDE_EFFECT: Writes to DB, Triggers background worker.
-#
-# @UX_STATE: Success -> 201 Created
-# @UX_STATE: Error(Validation) -> 400 Bad Request
-# @UX_STATE: Error(System) -> 500 Internal Server Error
+# @DATA_CONTRACT: Input -> CreateTaskRequest, Output -> Task
@router.post("/tasks", response_model=Task, status_code=status.HTTP_201_CREATED)
 async def create_task(
    request: CreateTaskRequest,
--- a/.ai/shots/critical_module.py
+++ b/.ai/shots/critical_module.py
@@ -1,9 +1,9 @@
 # [DEF:TransactionCore:Module]
-# @TIER: CRITICAL
+# @COMPLEXITY: 5
 # @SEMANTICS: Finance, ACID, Transfer, Ledger
 # @PURPOSE: Core banking transaction processor with ACID guarantees.
 # @LAYER: Domain (Core)
-# @RELATION: DEPENDS_ON -> [DEF:Infra:PostgresDB]
+# @RELATION: [DEPENDS_ON] ->[PostgresDB]
 #
 # @INVARIANT: Total system balance must remain constant (Double-Entry Bookkeeping).
 # @INVARIANT: Negative transfers are strictly forbidden.
@@ -33,14 +33,13 @@ class TransferResult(NamedTuple):
    new_balance: Decimal

 # [DEF:execute_transfer:Function]
+# @COMPLEXITY: 5
 # @PURPOSE: Atomically move funds between accounts with audit trails.
-# @DATA_CONTRACT: Input -> (sender_id: str, receiver_id: str, amount: Decimal), Output -> TransferResult
+# @RELATION: [CALLS] ->[atomic_transaction]
 # @PRE: amount > 0; sender != receiver; sender_balance >= amount.
 # @POST: sender_balance -= amount; receiver_balance += amount; Audit Record Created.
 # @SIDE_EFFECT: Database mutation (Rows locked), Audit IO.
-#
-# @UX_STATE: Success -> Returns 200 OK + Transaction Receipt.
-# @UX_STATE: Error(LowBalance) -> 422 Unprocessable -> UI shows "Top-up needed" modal.
+# @DATA_CONTRACT: Input -> (sender_id: str, receiver_id: str, amount: Decimal), Output -> TransferResult
 def execute_transfer(sender_id: str, receiver_id: str, amount: Decimal) -> TransferResult:
    # Guard: Input Validation (Вне belief_scope, так как это trivial проверка)
    if amount <= Decimal("0.00"):
@@ -54,7 +53,6 @@ def execute_transfer(sender_id: str, receiver_id: str, amount: Decimal) -> Trans
        logger.reason("Initiating transfer", extra={"from": sender_id, "to": receiver_id, "amount": amount})

        try:
-            # @RELATION: CALLS -> atomic_transaction
            with atomic_transaction():
                current_balance = get_balance(sender_id, for_update=True)
                
--- a/.ai/shots/frontend_component.svelte
+++ b/.ai/shots/frontend_component.svelte
@@ -1,18 +1,27 @@
 <!-- [DEF:FrontendComponentShot:Component] -->
 <!--
 /**
- * @TIER: CRITICAL
+ * @COMPLEXITY: 5
 * @SEMANTICS: Task, Button, Action, UX
 * @PURPOSE: Action button to spawn a new task with full UX feedback cycle.
 * @LAYER: UI (Presentation)
- * @RELATION: CALLS -> postApi
+ * @RELATION: [CALLS] ->[postApi]
 *
 * @INVARIANT: Must prevent double-submission while loading.
 * @INVARIANT: Loading state must always terminate (no infinite spinner).
 * @INVARIANT: User must receive feedback on both success and failure.
 *
+ * @SIDE_EFFECT: Sends network request and emits toast notifications.
+ * @DATA_CONTRACT: Input -> { plugin_id: string, params: object }, Output -> { task_id?: string }
+ *
 * @UX_REACTIVITY: Props -> $props(), LocalState -> $state(isLoading).
- * 
+ * @UX_STATE: Idle -> Button enabled, primary color, no spinner.
+ * @UX_STATE: Loading -> Button disabled, spinner visible, aria-busy=true.
+ * @UX_STATE: Success -> Toast success displayed.
+ * @UX_STATE: Error -> Toast error displayed.
+ * @UX_FEEDBACK: toast.success, toast.error
+ * @UX_RECOVERY: Error -> Keep form interactive and allow retry after failure.
+ *
 * @TEST_CONTRACT: ComponentState ->
 * {
 *   required_fields: { isLoading: bool },
@@ -21,26 +30,13 @@
 *     "isLoading=true implies aria-busy=true"
 *   ]
 * }
- *
 * @TEST_FIXTURE: idle_state -> { isLoading: false }
 * @TEST_FIXTURE: successful_response -> { task_id: "task_123" }
- * 
 * @TEST_EDGE: api_failure -> raises Error("Network")
 * @TEST_EDGE: empty_response -> {}
 * @TEST_EDGE: rapid_double_click -> special: concurrent_click
- * 
 * @TEST_INVARIANT: prevent_double_submission -> VERIFIED_BY:[rapid_double_click]
 * @TEST_INVARIANT: feedback_always_emitted -> VERIFIED_BY:[successful_response, api_failure]
- *
- * @UX_STATE: Idle -> Button enabled, primary color, no spinner.
- * @UX_STATE: Loading -> Button disabled, spinner visible, aria-busy=true.
- * @UX_STATE: Success -> Toast success displayed.
- * @UX_STATE: Error -> Toast error displayed.
- *
- * @UX_FEEDBACK: toast.success, toast.error
- *
- * @UX_TEST: Idle -> {click: spawnTask, expected: isLoading=true}
- * @UX_TEST: Loading -> {double_click: ignored, expected: single_api_call}
 */
 -->
 <script>
--- a/.ai/shots/plugin_example.py
+++ b/.ai/shots/plugin_example.py
@@ -1,10 +1,9 @@
 # [DEF:PluginExampleShot:Module]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @SEMANTICS: Plugin, Core, Extension
 # @PURPOSE: Reference implementation of a plugin following GRACE standards.
 # @LAYER: Domain (Business Logic)
-# @RELATION: INHERITS -> PluginBase
-# @INVARIANT: get_schema must return valid JSON Schema.
+# @RELATION: [INHERITS] ->[PluginBase]

 from typing import Dict, Any, Optional
 from ..core.plugin_base import PluginBase
@@ -14,6 +13,7 @@ from ..core.logger import logger, belief_scope

 # [DEF:ExamplePlugin:Class]
 # @PURPOSE: A sample plugin to demonstrate execution context and logging.
+# @RELATION: [INHERITS] ->[PluginBase]
 class ExamplePlugin(PluginBase):
    @property
    def id(self) -> str:
@@ -21,7 +21,6 @@ class ExamplePlugin(PluginBase):

    #[DEF:get_schema:Function]
    # @PURPOSE: Defines input validation schema.
-    # @DATA_CONTRACT: Input -> None, Output -> Dict (JSON Schema draft 7)
    def get_schema(self) -> Dict[str, Any]:
        return {
            "type": "object",
@@ -36,8 +35,9 @@ class ExamplePlugin(PluginBase):
    #[/DEF:get_schema:Function]

    # [DEF:execute:Function]
+    # @COMPLEXITY: 4
    # @PURPOSE: Core plugin logic with structured logging and scope isolation.
-    # @DATA_CONTRACT: Input -> (params: Dict, context: Optional[TaskContext]), Output -> None
+    # @RELATION: [BINDS_TO] ->[context.logger]
    # @PRE: params must be validated against get_schema() before calling.
    # @POST: Plugin payload is processed; progress is reported if context exists.
    # @SIDE_EFFECT: Emits logs to centralized system and TaskContext.
--- a/.ai/shots/trivial_utility.py
+++ b/.ai/shots/trivial_utility.py
@@ -0,0 +1,40 @@
+# [DEF:TrivialUtilityShot:Module]
+# @COMPLEXITY: 1
+# @PURPOSE: Reference implementation of a zero-overhead utility using implicit Complexity 1.
+
+import re
+from datetime import datetime, timezone
+from typing import Optional
+
+# [DEF:slugify:Function]
+# @PURPOSE: Converts a string to a URL-safe slug.
+def slugify(text: str) -> str:
+    if not text:
+        return ""
+    text = text.lower().strip()
+    text = re.sub(r'[^\w\s-]', '', text)
+    return re.sub(r'[-\s]+', '-', text)
+# [/DEF:slugify:Function]
+
+# [DEF:get_utc_now:Function]
+def get_utc_now() -> datetime:
+    """Returns current UTC datetime (purpose is omitted because it's obvious)."""
+    return datetime.now(timezone.utc)
+# [/DEF:get_utc_now:Function]
+
+# [DEF:PaginationDTO:Class]
+class PaginationDTO:
+    # [DEF:__init__:Function]
+    def __init__(self, page: int = 1, size: int = 50):
+        self.page = max(1, page)
+        self.size = min(max(1, size), 1000)
+    # [/DEF:__init__:Function]
+
+    # [DEF:offset:Function]
+    @property
+    def offset(self) -> int:
+        return (self.page - 1) * self.size
+    # [/DEF:offset:Function]
+# [/DEF:PaginationDTO:Class]
+
+# [/DEF:TrivialUtilityShot:Module]
--- a/.ai/standards/semantics.md
+++ b/.ai/standards/semantics.md
@@ -30,7 +30,7 @@

 ## III. ТОПОЛОГИЯ ФАЙЛА (СТРОГИЙ ПОРЯДОК)
 1. **HEADER (Заголовок):**[DEF:filename:Module]
-   @TIER: [CRITICAL | STANDARD | TRIVIAL]
+   @COMPLEXITY: [1|2|3|4|5] *(алиас: `@C:`; legacy `@TIER` допустим только для обратной совместимости)*
   @SEMANTICS: [keywords]
   @PURPOSE: [Однострочная суть]
   @LAYER: [Domain | UI | Infra]
@@ -40,7 +40,7 @@
 3. **FOOTER (Подвал):** [/DEF:filename:Module]

 ## IV. КОНТРАКТЫ (DESIGN BY CONTRACT & UX)
-Обязательны для TIER: CRITICAL и STANDARD. Заменяют стандартные Docstrings.
+Контракты требуются адаптивно по уровню сложности, а не по жесткому tier.

 **[CORE CONTRACTS]:**
 - `@PURPOSE:` Суть функции/компонента.
@@ -62,11 +62,40 @@
 - `@TEST_EDGE: [Название] ->[Сбой]` (Минимум 3: missing_field, invalid_type, external_fail).
 - `@TEST_INVARIANT: [Имя] -> VERIFIED_BY: [scenario_1, ...]`

-## V. УРОВНИ СТРОГОСТИ (TIERS)
-Степень контроля задается в Header.
- **CRITICAL** (Ядро/Деньги/Безопасность): 100% покрытие тегами GRACE. Обязательны: Граф, Инварианты, Логи `logger.reason/reflect`, все `@UX` и `@TEST` теги. Использование `belief_scope` строго обязательно.
- **STANDARD** (Бизнес-логика / Типовые формы): Базовый уровень. Обязательны: `@PURPOSE`, `@UX_STATE`, `@RELATION`, базовое логирование.
- **TRIVIAL** (Утилиты / DTO / Атомы UI): Минимальный каркас. Только якоря `[DEF]...[/DEF]` и `@PURPOSE`.
+## V. ШКАЛА СЛОЖНОСТИ (COMPLEXITY 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` строго обязательно.
+
+**Legacy mapping (обратная совместимость):**
+- `@TIER: TRIVIAL` -> Complexity 1
+- `@TIER: STANDARD` -> Complexity 3
+- `@TIER: CRITICAL` -> Complexity 5

 ## VI. ПРОТОКОЛ ЛОГИРОВАНИЯ (THREAD-LOCAL BELIEF STATE)
 Логирование — это механизм трассировки рассуждений ИИ (CoT) и управления Attention Energy. Архитектура использует Thread-local storage (`_belief_state`), поэтому `ID` прокидывается автоматически.
@@ -90,11 +119,11 @@

 ## VII. АЛГОРИТМ ИСПОЛНЕНИЯ И САМОКОРРЕКЦИИ
 **[PHASE_1: ANALYSIS]**
-Оцени TIER, Layer и UX-требования. При слепоте контекста -> `yield [NEED_CONTEXT: id]`.
+Оцени Complexity, Layer и UX-требования. При слепоте контекста -> `yield [NEED_CONTEXT: id]`.
 **[PHASE_2: SYNTHESIS]**
-Сгенерируй каркас из `[DEF]`, Header и Контрактов.
+Сгенерируй каркас из `[DEF]`, Header и только тех контрактов, которые соответствуют уровню сложности.
 **[PHASE_3: IMPLEMENTATION]**
-Напиши код строго по Контракту. Для CRITICAL секций открой `with belief_scope("ID"):` и орошай путь вызовами `logger.reason()` и `logger.reflect()`.
+Напиши код строго по Контракту. Для Complexity 5 секций открой `with belief_scope("ID"):` и орошай путь вызовами `logger.reason()` и `logger.reflect()`.
 **[PHASE_4: CLOSURE]**
 Убедись, что все `[DEF]` закрыты соответствующими `[/DEF]`.