refactor(semantics): migrate legacy @TIER to @COMPLEXITY annotations

- Replaced @TIER: TRIVIAL with @COMPLEXITY: 1
- Replaced @TIER: STANDARD with @COMPLEXITY: 3
- Replaced @TIER: CRITICAL with @COMPLEXITY: 5
- Manually elevated specific critical/complex components to levels 2 and 4
- Ignored legacy, specs, and node_modules directories
- Updated generated semantic map

backend/src/api/routes/assistant.py

@@ -1,5 +1,5 @@
 # [DEF:backend.src.api.routes.assistant:Module]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @SEMANTICS: api, assistant, chat, command, confirmation
 # @PURPOSE: API routes for LLM assistant command parsing and safe execution orchestration.
 # @LAYER: API
@@ -47,7 +47,7 @@ git_service = GitService()
 
 
 # [DEF:AssistantMessageRequest:Class]
-# @TIER: TRIVIAL
+# @COMPLEXITY: 1
 # @PURPOSE: Input payload for assistant message endpoint.
 # @PRE: message length is within accepted bounds.
 # @POST: Request object provides message text and optional conversation binding.
@@ -58,7 +58,7 @@ class AssistantMessageRequest(BaseModel):
 
 
 # [DEF:AssistantAction:Class]
-# @TIER: TRIVIAL
+# @COMPLEXITY: 1
 # @PURPOSE: UI action descriptor returned with assistant responses.
 # @PRE: type and label are provided by orchestration logic.
 # @POST: Action can be rendered as button on frontend.
@@ -70,7 +70,7 @@ class AssistantAction(BaseModel):
 
 
 # [DEF:AssistantMessageResponse:Class]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Output payload contract for assistant interaction endpoints.
 # @PRE: Response includes deterministic state and text.
 # @POST: Payload may include task_id/confirmation_id/actions for UI follow-up.
@@ -88,7 +88,7 @@ class AssistantMessageResponse(BaseModel):
 
 
 # [DEF:ConfirmationRecord:Class]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: In-memory confirmation token model for risky operation dispatch.
 # @PRE: intent/dispatch/user_id are populated at confirmation request time.
 # @POST: Record tracks lifecycle state and expiry timestamp.
@@ -125,7 +125,7 @@ INTENT_PERMISSION_CHECKS: Dict[str, List[Tuple[str, str]]] = {
 
 
 # [DEF:_append_history:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Append conversation message to in-memory history buffer.
 # @PRE: user_id and conversation_id identify target conversation bucket.
 # @POST: Message entry is appended to CONVERSATIONS key list.
@@ -157,7 +157,7 @@ def _append_history(
 
 
 # [DEF:_persist_message:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Persist assistant/user message record to database.
 # @PRE: db session is writable and message payload is serializable.
 # @POST: Message row is committed or persistence failure is logged.
@@ -193,7 +193,7 @@ def _persist_message(
 
 
 # [DEF:_audit:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Append in-memory audit record for assistant decision trace.
 # @PRE: payload describes decision/outcome fields.
 # @POST: ASSISTANT_AUDIT list for user contains new timestamped entry.
@@ -206,7 +206,7 @@ def _audit(user_id: str, payload: Dict[str, Any]):
 
 
 # [DEF:_persist_audit:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Persist structured assistant audit payload in database.
 # @PRE: db session is writable and payload is JSON-serializable.
 # @POST: Audit row is committed or failure is logged with rollback.
@@ -230,7 +230,7 @@ def _persist_audit(db: Session, user_id: str, payload: Dict[str, Any], conversat
 
 
 # [DEF:_persist_confirmation:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Persist confirmation token record to database.
 # @PRE: record contains id/user/intent/dispatch/expiry fields.
 # @POST: Confirmation row exists in persistent storage.
@@ -256,7 +256,7 @@ def _persist_confirmation(db: Session, record: ConfirmationRecord):
 
 
 # [DEF:_update_confirmation_state:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Update persistent confirmation token lifecycle state.
 # @PRE: confirmation_id references existing row.
 # @POST: State and consumed_at fields are updated when applicable.
@@ -276,7 +276,7 @@ def _update_confirmation_state(db: Session, confirmation_id: str, state: str):
 
 
 # [DEF:_load_confirmation_from_db:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Load confirmation token from database into in-memory model.
 # @PRE: confirmation_id may or may not exist in storage.
 # @POST: Returns ConfirmationRecord when found, otherwise None.
@@ -302,7 +302,7 @@ def _load_confirmation_from_db(db: Session, confirmation_id: str) -> Optional[Co
 
 
 # [DEF:_ensure_conversation:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve active conversation id in memory or create a new one.
 # @PRE: user_id identifies current actor.
 # @POST: Returns stable conversation id and updates USER_ACTIVE_CONVERSATION.
@@ -322,7 +322,7 @@ def _ensure_conversation(user_id: str, conversation_id: Optional[str]) -> str:
 
 
 # [DEF:_resolve_or_create_conversation:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve active conversation using explicit id, memory cache, or persisted history.
 # @PRE: user_id and db session are available.
 # @POST: Returns conversation id and updates USER_ACTIVE_CONVERSATION cache.
@@ -352,7 +352,7 @@ def _resolve_or_create_conversation(user_id: str, conversation_id: Optional[str]
 
 
 # [DEF:_cleanup_history_ttl:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Enforce assistant message retention window by deleting expired rows and in-memory records.
 # @PRE: db session is available and user_id references current actor scope.
 # @POST: Messages older than ASSISTANT_MESSAGE_TTL_DAYS are removed from persistence and memory mirrors.
@@ -390,7 +390,7 @@ def _cleanup_history_ttl(db: Session, user_id: str):
 
 
 # [DEF:_is_conversation_archived:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Determine archived state for a conversation based on last update timestamp.
 # @PRE: updated_at can be null for empty conversations.
 # @POST: Returns True when conversation inactivity exceeds archive threshold.
@@ -403,7 +403,7 @@ def _is_conversation_archived(updated_at: Optional[datetime]) -> bool:
 
 
 # [DEF:_coerce_query_bool:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Normalize bool-like query values for compatibility in direct handler invocations/tests.
 # @PRE: value may be bool, string, or FastAPI Query metadata object.
 # @POST: Returns deterministic boolean flag.
@@ -417,7 +417,7 @@ def _coerce_query_bool(value: Any) -> bool:
 
 
 # [DEF:_extract_id:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Extract first regex match group from text by ordered pattern list.
 # @PRE: patterns contain at least one capture group.
 # @POST: Returns first matched token or None.
@@ -431,7 +431,7 @@ def _extract_id(text: str, patterns: List[str]) -> Optional[str]:
 
 
 # [DEF:_resolve_env_id:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve environment identifier/name token to canonical environment id.
 # @PRE: config_manager provides environment list.
 # @POST: Returns matched environment id or None.
@@ -449,7 +449,7 @@ def _resolve_env_id(token: Optional[str], config_manager: ConfigManager) -> Opti
 
 
 # [DEF:_is_production_env:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Determine whether environment token resolves to production-like target.
 # @PRE: config_manager provides environments or token text is provided.
 # @POST: Returns True for production/prod synonyms, else False.
@@ -467,7 +467,7 @@ def _is_production_env(token: Optional[str], config_manager: ConfigManager) -> b
 
 
 # [DEF:_resolve_provider_id:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve provider token to provider id with active/default fallback.
 # @PRE: db session can load provider list through LLMProviderService.
 # @POST: Returns provider id or None when no providers configured.
@@ -503,7 +503,7 @@ def _resolve_provider_id(
 
 
 # [DEF:_get_default_environment_id:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve default environment id from settings or first configured environment.
 # @PRE: config_manager returns environments list.
 # @POST: Returns default environment id or None when environment list is empty.
@@ -525,7 +525,7 @@ def _get_default_environment_id(config_manager: ConfigManager) -> Optional[str]:
 
 
 # [DEF:_resolve_dashboard_id_by_ref:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve dashboard id by title or slug reference in selected environment.
 # @PRE: dashboard_ref is a non-empty string-like token.
 # @POST: Returns dashboard id when uniquely matched, otherwise None.
@@ -568,7 +568,7 @@ def _resolve_dashboard_id_by_ref(
 
 
 # [DEF:_resolve_dashboard_id_entity:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve dashboard id from intent entities using numeric id or dashboard_ref fallback.
 # @PRE: entities may contain dashboard_id as int/str and optional dashboard_ref.
 # @POST: Returns resolved dashboard id or None when ambiguous/unresolvable.
@@ -600,7 +600,7 @@ def _resolve_dashboard_id_entity(
 
 
 # [DEF:_get_environment_name_by_id:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Resolve human-readable environment name by id.
 # @PRE: environment id may be None.
 # @POST: Returns matching environment name or fallback id.
@@ -613,7 +613,7 @@ def _get_environment_name_by_id(env_id: Optional[str], config_manager: ConfigMan
 
 
 # [DEF:_extract_result_deep_links:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Build deep-link actions to verify task result from assistant chat.
 # @PRE: task object is available.
 # @POST: Returns zero or more assistant actions for dashboard open/diff.
@@ -670,7 +670,7 @@ def _extract_result_deep_links(task: Any, config_manager: ConfigManager) -> List
 
 
 # [DEF:_build_task_observability_summary:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Build compact textual summary for completed tasks to reduce "black box" effect.
 # @PRE: task may contain plugin-specific result payload.
 # @POST: Returns non-empty summary line for known task types or empty string fallback.
@@ -734,7 +734,7 @@ def _build_task_observability_summary(task: Any, config_manager: ConfigManager)
 
 
 # [DEF:_parse_command:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Deterministically parse RU/EN command text into intent payload.
 # @PRE: message contains raw user text and config manager resolves environments.
 # @POST: Returns intent dict with domain/operation/entities/confidence/risk fields.
@@ -928,7 +928,7 @@ def _parse_command(message: str, config_manager: ConfigManager) -> Dict[str, Any
 
 
 # [DEF:_check_any_permission:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Validate user against alternative permission checks (logical OR).
 # @PRE: checks list contains resource-action tuples.
 # @POST: Returns on first successful permission; raises 403-like HTTPException otherwise.
@@ -946,7 +946,7 @@ def _check_any_permission(current_user: User, checks: List[Tuple[str, str]]):
 
 
 # [DEF:_has_any_permission:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Check whether user has at least one permission tuple from the provided list.
 # @PRE: current_user and checks list are valid.
 # @POST: Returns True when at least one permission check passes.
@@ -960,7 +960,7 @@ def _has_any_permission(current_user: User, checks: List[Tuple[str, str]]) -> bo
 
 
 # [DEF:_build_tool_catalog:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Build current-user tool catalog for LLM planner with operation contracts and defaults.
 # @PRE: current_user is authenticated; config/db are available.
 # @POST: Returns list of executable tools filtered by permission and runtime availability.
@@ -1084,7 +1084,7 @@ def _build_tool_catalog(current_user: User, config_manager: ConfigManager, db: S
 
 
 # [DEF:_coerce_intent_entities:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Normalize intent entity value types from LLM output to route-compatible values.
 # @PRE: intent contains entities dict or missing entities.
 # @POST: Returned intent has numeric ids coerced where possible and string values stripped.
@@ -1109,7 +1109,7 @@ _SAFE_OPS = {"show_capabilities", "get_task_status", "get_health_summary"}
 
 
 # [DEF:_confirmation_summary:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Build human-readable confirmation prompt for an intent before execution.
 # @PRE: intent contains operation and entities fields.
 # @POST: Returns descriptive Russian-language text ending with confirmation prompt.
@@ -1205,7 +1205,7 @@ async def _async_confirmation_summary(intent: Dict[str, Any], config_manager: Co
 
 
 # [DEF:_clarification_text_for_intent:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Convert technical missing-parameter errors into user-facing clarification prompts.
 # @PRE: state was classified as needs_clarification for current intent/error combination.
 # @POST: Returned text is human-readable and actionable for target operation.
@@ -1229,7 +1229,7 @@ def _clarification_text_for_intent(intent: Optional[Dict[str, Any]], detail_text
 
 
 # [DEF:_plan_intent_with_llm:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Use active LLM provider to select best tool/operation from dynamic catalog.
 # @PRE: tools list contains allowed operations for current user.
 # @POST: Returns normalized intent dict when planning succeeds; otherwise None.
@@ -1340,7 +1340,7 @@ async def _plan_intent_with_llm(
 
 
 # [DEF:_authorize_intent:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Validate user permissions for parsed intent before confirmation/dispatch.
 # @PRE: intent.operation is present for known assistant command domains.
 # @POST: Returns if authorized; raises HTTPException(403) when denied.
@@ -1352,7 +1352,7 @@ def _authorize_intent(intent: Dict[str, Any], current_user: User):
 
 
 # [DEF:_dispatch_intent:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Execute parsed assistant intent via existing task/plugin/git services.
 # @PRE: intent operation is known and actor permissions are validated per operation.
 # @POST: Returns response text, optional task id, and UI actions for follow-up.
@@ -1674,7 +1674,7 @@ async def _dispatch_intent(
 
 @router.post("/messages", response_model=AssistantMessageResponse)
 # [DEF:send_message:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Parse assistant command, enforce safety gates, and dispatch executable intent.
 # @PRE: Authenticated user is available and message text is non-empty.
 # @POST: Response state is one of clarification/confirmation/started/success/denied/failed.
@@ -1844,7 +1844,7 @@ async def send_message(
 
 @router.post("/confirmations/{confirmation_id}/confirm", response_model=AssistantMessageResponse)
 # [DEF:confirm_operation:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Execute previously requested risky operation after explicit user confirmation.
 # @PRE: confirmation_id exists, belongs to current user, is pending, and not expired.
 # @POST: Confirmation state becomes consumed and operation result is persisted in history.
@@ -1911,7 +1911,7 @@ async def confirm_operation(
 
 @router.post("/confirmations/{confirmation_id}/cancel", response_model=AssistantMessageResponse)
 # [DEF:cancel_operation:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Cancel pending risky operation and mark confirmation token as cancelled.
 # @PRE: confirmation_id exists, belongs to current user, and is still pending.
 # @POST: Confirmation becomes cancelled and cannot be executed anymore.
@@ -1968,7 +1968,7 @@ async def cancel_operation(
 
 
 # [DEF:list_conversations:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Return paginated conversation list for current user with archived flag and last message preview.
 # @PRE: Authenticated user context and valid pagination params.
 # @POST: Conversations are grouped by conversation_id sorted by latest activity descending.
@@ -2056,7 +2056,7 @@ async def list_conversations(
 
 
 # [DEF:delete_conversation:Function]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Soft-delete or hard-delete a conversation and clear its in-memory trace.
 # @PRE: conversation_id belongs to current_user.
 # @POST: Conversation records are removed from DB and CONVERSATIONS cache.