Sync .cursor from detections

.cursor/rules/coderule.mdc

@@ -4,7 +4,12 @@ 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
+- 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 
@@ -13,6 +18,7 @@ alwaysApply: true
 - 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.

.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

@@ -6,3 +6,5 @@ alwaysApply: true
 
 - Work on the `dev` branch
 - 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/meta-rule.mdc

@@ -31,3 +31,20 @@ When the user reacts negatively to generated code ("WTF", "what the hell", "why
 **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.