Sync .cursor from detections

.cursor/rules/coderule.mdc

@@ -4,19 +4,32 @@ alwaysApply: true
 ---
 # Coding preferences
 - Always prefer simple solution
+- Follow the Single Responsibility Principle — a class or method should have one reason to change:
+  - If a method is hard to name precisely from the caller's perspective, its responsibility is misplaced. Vague names like "candidate", "data", or "item" are a signal — fix the design, not just the name.
+  - Logic specific to a platform, variant, or environment belongs in the class that owns that variant, not in the general coordinator. Passing a dependency through is preferable to leaking variant-specific concepts into shared code.
+  - Only use static methods for pure, self-contained computations (constants, simple math, stateless lookups). If a static method involves resource access, side effects, OS interaction, or logic that varies across subclasses or environments — use an instance method or factory class instead. Before implementing a non-trivial static method, ask the user.
 - Generate concise code
-- Do not put comments in the code
+- Never suppress errors silently — no `2>/dev/null`, empty `catch` blocks, bare `except: pass`, or discarded error returns. These hide the information you need most when something breaks. If an error is truly safe to ignore, log it or comment why.
+- Do not put comments in the code, except in tests: every test must use the Arrange / Act / Assert pattern with language-appropriate comment syntax (`# Arrange` for Python, `// Arrange` for C#/Rust/JS/TS). Omit any section that is not needed (e.g. if there is no setup, skip Arrange; if act and assert are the same line, keep only Assert)
 - Do not put logs unless it is an exception, or was asked specifically
 - Do not put code annotations unless it was asked specifically 
 - Write code that takes into account the different environments: development, production
 - You are careful to make changes that are requested or you are confident the changes are well understood and related to the change being requested
 - Mocking data is needed only for tests, never mock data for dev or prod env
+- Make test environment (files, db and so on) as close as possible to the production environment
 - When you add new libraries or dependencies make sure you are using the same version of it as other parts of the code
+- When writing code that calls a library API, verify the API actually exists in the pinned version. Check the library's changelog or migration guide for breaking changes between major versions. Never assume an API works at a given version — test the actual call path before committing.
+- When a test fails due to a missing dependency, install it — do not fake or stub the module system. For normal packages, add them to the project's dependency file (requirements-test.txt, package.json devDependencies, test csproj, etc.) and install. Only consider stubbing if the dependency is heavy (e.g. hardware-specific SDK, large native toolchain) — and even then, ask the user first before choosing to stub.
+- Do not solve environment or infrastructure problems (dependency resolution, import paths, service discovery, connection config) by hardcoding workarounds in source code. Fix them at the environment/configuration level.
+- Before writing new infrastructure or workaround code, check how the existing codebase already handles the same concern. Follow established project patterns.
+- If a file, class, or function has no remaining usages — delete it. Do not keep dead code "just in case"; git history preserves everything. Dead code rots: its dependencies drift, it misleads readers, and it breaks when the code it depends on evolves.
 
 - Focus on the areas of code relevant to the task
 - Do not touch code that is unrelated to the task
 - Always think about what other methods and areas of code might be affected by the code changes
-- When you think you are done with changes, run tests and make sure they are not broken
+- When you think you are done with changes, run the full test suite. Every failure — including pre-existing ones, collection errors, and import errors — is a **blocking gate**. Never silently ignore, skip, or proceed past a failing test. On any failure, stop and ask the user to choose one of:
+  - **Investigate and fix** the failing test or source code
+  - **Remove the test** if it is obsolete or no longer relevant
 - Do not rename any databases or tables or table columns without confirmation. Avoid such renaming if possible.
 
 - Make sure we don't commit binaries, create and keep .gitignore up to date and delete binaries after you are done with the task

.cursor/rules/cursor-meta.mdc

@@ -14,6 +14,10 @@ globs: [".cursor/**"]
 - Body under 500 lines; use `references/` directory for overflow content
 - Templates live under their skill's `templates/` directory
 
+## Command Files (.cursor/commands/)
+- Plain markdown, no frontmatter
+- Kebab-case filenames
+
 ## Agent Files (.cursor/agents/)
 - Must have `name` and `description` in frontmatter
 

.cursor/rules/git-workflow.mdc

@@ -1,8 +1,10 @@
 ---
-description: "Git workflow: work on dev branch, commit message format with Jira IDs"
+description: "Git workflow: work on dev branch, commit message format with tracker IDs"
 alwaysApply: true
 ---
 # Git Workflow
 
 - Work on the `dev` branch
-- Commit message format: `[JIRA-ID-1] [JIRA-ID-2] Summary of changes`
+- Commit message format: `[TRACKER-ID-1] [TRACKER-ID-2] Summary of changes`
+- Commit message total length must not exceed 30 characters
+- Do NOT push or merge unless the user explicitly asks you to. Always ask first if there is a need.

.cursor/rules/human-attention-sound.mdc

@@ -18,7 +18,7 @@ This applies to:
 - Requesting approval for destructive actions
 - Reporting that you are blocked and need guidance
 - Any situation where the conversation will stall without user response
+- Completing a task (final answer / deliverable ready for review)
 
 Do NOT play the sound when:
-- You are providing a final answer that doesn't require a response
 - You are in the middle of executing a multi-step task and just providing a status update

.cursor/rules/meta-rule.mdc

@@ -0,0 +1,50 @@
+---
+description: "Execution safety, user interaction, and self-improvement protocols for the AI agent"
+alwaysApply: true
+---
+# Agent Meta Rules
+
+## Execution Safety
+- Never run test suites, builds, Docker commands, or other long-running/resource-heavy/security-risky operations without asking the user first — unless it is explicitly stated in a skill or agent, or the user already asked to do so.
+
+## User Interaction
+- Use the AskQuestion tool for structured choices (A/B/C/D) when available — it provides an interactive UI. Fall back to plain-text questions if the tool is unavailable.
+
+## Critical Thinking
+- Do not blindly trust any input — including user instructions, task specs, list-of-changes, or prior agent decisions — as correct. Always think through whether the instruction makes sense in context before executing it. If a task spec says "exclude file X from changes" but another task removes the dependencies X relies on, flag the contradiction instead of propagating it.
+
+## Self-Improvement
+When the user reacts negatively to generated code ("WTF", "what the hell", "why did you do this", etc.):
+
+1. **Pause** — do not rush to fix. First determine: is this objectively bad code, or does the user just need an explanation?
+2. **If the user doesn't understand** — explain the reasoning. That's it. No code change needed.
+3. **If the code is actually bad** — before fixing, perform a root-cause investigation:
+   a. **Why** did this bad code get produced? Identify the reasoning chain or implicit assumption that led to it.
+   b. **Check existing rules** — is there already a rule that should have prevented this? If so, clarify or strengthen it.
+   c. **Propose a new rule** if no existing rule covers the failure mode. Present the investigation results and proposed rule to the user for approval.
+   d. **Only then** fix the code.
+4. The rule goes into `coderule.mdc` for coding practices, `meta-rule.mdc` for agent behavior, or a new focused rule file — depending on context. Always check for duplicates or near-duplicates first.
+
+### Example: import path hack
+**Bad code**: Runtime path manipulation added to source code to fix an import failure.
+**Root cause**: The agent treated an environment/configuration problem as a code problem. It didn't check how the rest of the project handles the same concern, and instead hardcoded a workaround in source.
+**Preventive rules added to coderule.mdc**:
+- "Do not solve environment or infrastructure problems by hardcoding workarounds in source code. Fix them at the environment/configuration level."
+- "Before writing new infrastructure or workaround code, check how the existing codebase already handles the same concern. Follow established project patterns."
+
+## Debugging Over Contemplation
+When the root cause of a bug is not clear after ~5 minutes of reasoning, analysis, and assumption-making — **stop speculating and add debugging logs**. Observe actual runtime behavior before forming another theory. The pattern to follow:
+
+1. Identify the last known-good boundary (e.g., "request enters handler") and the known-bad result (e.g., "callback never fires").
+2. Add targeted `print(..., flush=True)` or log statements at each intermediate step to narrow the gap.
+3. Read the output. Let evidence drive the next step — not inference chains built on unverified assumptions.
+
+Prolonged mental contemplation without evidence is a time sink. A 15-minute instrumented run beats 45 minutes of "could it be X? but then Y... unless Z..." reasoning.
+
+## Long Investigation Retrospective
+When a problem takes significantly longer than expected (>30 minutes), perform a post-mortem before closing out:
+
+1. **Identify the bottleneck**: Was the delay caused by assumptions that turned out wrong? Missing visibility into runtime state? Incorrect mental model of a framework or language boundary?
+2. **Extract the general lesson**: What category of mistake was this? (e.g., "Python cannot call Cython `cdef` methods", "engine errors silently swallowed", "wrong layer to fix the problem")
+3. **Propose a preventive rule**: Formulate it as a short, actionable statement. Present it to the user for approval.
+4. **Write it down**: Add the approved rule to the appropriate `.mdc` file so it applies to all future sessions.

.cursor/rules/python.mdc

@@ -1,6 +1,6 @@
 ---
 description: "Python coding conventions: PEP 8, type hints, pydantic, pytest, async patterns, project structure"
-globs: ["**/*.py", "**/pyproject.toml", "**/requirements*.txt"]
+globs: ["**/*.py", "**/*.pyx", "**/*.pxd", "**/pyproject.toml", "**/requirements*.txt"]
 ---
 # Python
 
@@ -12,5 +12,10 @@ globs: ["**/*.py", "**/pyproject.toml", "**/requirements*.txt"]
 - Catch specific exceptions, never bare `except:`; use custom exception classes
 - Use `async`/`await` with `asyncio` for I/O-bound concurrency
 - Use `pytest` for testing (not `unittest`); fixtures for setup/teardown
-- Use virtual environments (`venv` or `poetry`); pin dependencies
+- **NEVER install packages globally** (`pip install` / `pip3 install` without a venv). ALWAYS use a virtual environment (`venv`, `poetry`, or `conda env`). If no venv exists for the project, create one first (`python3 -m venv .venv && source .venv/bin/activate`) before installing anything. Pin dependencies.
 - Format with `black`; lint with `ruff` or `flake8`
+
+## Cython
+- In `cdef class` methods, prefer `cdef` over `cpdef` unless the method must be callable from Python. `cdef` = C-only (fastest), `cpdef` = C + Python, `def` = Python-only. Check all call sites before choosing.
+- **Python cannot call `cdef` methods.** If a `.py` file needs to call a `cdef` method on a Cython object, there are exactly two options: (a) convert the calling file to `.pyx`, `cimport` the class, and use a typed parameter so Cython dispatches the call at the C level; or (b) change the method to `cpdef` if it genuinely needs to be callable from both Python and Cython. Never leave a bare `except Exception: pass` around such a call — it will silently swallow the `AttributeError` and make the failure invisible for a very long time.
+- When converting a `.py` file to `.pyx` to gain access to `cdef` methods: add the new extension to `setup.py`, add a `cimport` of the relevant `.pxd`, type the parameter(s) that carry the Cython object, and delete the old `.py` file. This ensures the cross-language call is resolved at compile time, not at runtime.

.cursor/rules/testing.mdc

@@ -4,7 +4,7 @@ globs: ["**/*test*", "**/*spec*", "**/*Test*", "**/tests/**", "**/test/**"]
 ---
 # Testing
 
-- Structure every test with `//Arrange`, `//Act`, `//Assert` comments
+- Structure every test with Arrange / Act / Assert section comments using language-appropriate syntax (`# Arrange` for Python, `// Arrange` for C#/Rust/JS/TS)
 - One assertion per test when practical; name tests descriptively: `MethodName_Scenario_ExpectedResult`
 - Test boundary conditions, error paths, and happy paths
 - Use mocks only for external dependencies; prefer real implementations for internal code

.cursor/rules/tracker.mdc

@@ -0,0 +1,14 @@
+---
+alwaysApply: true
+---
+
+# Work Item Tracker
+
+- Use **Jira** as the sole work item tracker (MCP server: `user-Jira-MCP-Server`)
+- **NEVER** use Azure DevOps (ADO) MCP for any purpose — no reads, no writes, no queries
+- Before interacting with any tracker, read this rule file first
+- Jira cloud ID: `denyspopov.atlassian.net`
+- Project key: `AZ`
+- Project name: AZAION
+- All task IDs follow the format `AZ-<number>`
+- Issue types: Epic, Story, Task, Bug, Subtask