@bonesofspring/ai-rules 0.2.14 → 0.2.15

package/presets/cursor/next/rules/react-ui.mdc

@@ -1,95 +1,95 @@
 ---
-description: Паттерны React/Next UI и стилей (preset)
+description: React/Next UI and styling patterns (preset)
 globs: app/src/ui/**/*.tsx,app/src/ui/**/*.ts
 alwaysApply: false
 impact: HIGH
 ---
 
-# Общие правила компонентов
+# General component rules
 
-- Использовать **функциональные компоненты** с хуками, без классов.
-- Компонент должен:
-  - быть максимально "тонким" по бизнес‑логике;
-  - делегировать состояние в store/хуки, если оно нужно в нескольких местах;
-  - опираться на **общие UI‑примитивы дизайна проекта** (пакеты или локальная библиотека компонентов), если они есть.
-- Перед новым кастомным контролом — поискать готовый или близкий компонент в репозитории / пакетах UI проекта и переиспользовать или расширить его.
-- Для повторяемой логики создавать `useSomething`‑хуки рядом или в `src/ui/hooks/**`.
- - При обращении к store, API, общим хелперам и утилитам компоненты и хуки должны использовать только их **public API** (например, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), а не импортировать внутренние файлы реализации других модулей.
+- Use **functional components** with hooks, no classes.
+- A component should:
+  - stay as "thin" as possible on business logic;
+  - delegate state to store/hooks when needed in multiple places;
+  - rely on **shared project UI design primitives** (packages or local component library), if present.
+- Before a new custom control — search for an existing or close component in the repository / project UI packages and reuse or extend it.
+- For repeated logic, create `useSomething` hooks nearby or in `src/ui/hooks/**`.
+ - When accessing store, API, shared helpers, and utilities, components and hooks must use only their **public API** (for example, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), not internal implementation files of other modules.
 
-# Структура файлов
+# File structure
 
-Для страницы/крупного блока:
-- `FeatureBlock.tsx` — JSX и композиция.
-- `styles.ts` или соседний модуль стилей — по конвенции репозитория (CSS Modules, CSS-in-JS, и т.д.).
-- `index.ts` — реэкспорт (если нужно наружу).
+For a page/large block:
+- `FeatureBlock.tsx` — JSX and composition.
+- `styles.ts` or adjacent style module — per repository convention (CSS Modules, CSS-in-JS, etc.).
+- `index.ts` — re-export (if needed externally).
 
-## Дочерние компоненты (`./components`)
+## Child components (`./components`)
 
-- Локальные подкомпоненты, используемые только этим блоком, выносятся в **`./components/<ComponentName>/`** относительно папки родительского компонента (не оставлять крупные куски JSX и «внутренние» компоненты в том же файле, что и родитель).
-- У каждого такого подкомпонента — **своя** папка с тем же именем, что и публичное имя компонента:
-  - `ComponentName.tsx` — разметка и композиция;
-  - `styles.ts` — только стили этого подкомпонента (не тянуть `styles` соседних компонентов — см. § Стили ниже);
-  - при необходимости — `ComponentName.data.ts`, `ComponentName.utils.ts`, `ComponentName.hooks.ts` по тем же правилам префикса, что и у родителя;
-  - опционально `index.ts` с реэкспортом.
-- Родитель импортирует подкомпонент из `./components/...`, а не держит его реализацию inline.
+- Local subcomponents used only by this block go in **`./components/<ComponentName>/`** relative to the parent component folder (do not leave large JSX chunks and "internal" components in the same file as the parent).
+- Each subcomponent has **its own** folder with the same name as the public component:
+  - `ComponentName.tsx` — markup and composition;
+  - `styles.ts` — styles for this subcomponent only (do not import `styles` from sibling components — see Styles below);
+  - when needed — `ComponentName.data.ts`, `ComponentName.utils.ts`, `ComponentName.hooks.ts` with the same prefix rules as the parent;
+  - optional `index.ts` re-export.
+- The parent imports subcomponents from `./components/...`, not inline implementations.
 
-Для переиспользуемого компонента:
-- Папка с именем компонента:
+For a reusable component:
+- Folder named after the component:
   - `ComponentName.tsx`
-  - файлы стилей по принятой схеме;
-  - опционально: `types.ts`, `ComponentName.hooks.ts` (см. ниже про префикс).
+  - style files per project scheme;
+  - optional: `types.ts`, `ComponentName.hooks.ts` (see prefix rules below).
 
-## Вспомогательные модули рядом с компонентом (именование)
+## Adjacent helper modules (naming)
 
-**Префикс имени файла = публичное имя компонента** (как у `ComponentName.tsx` в этой папке), в **PascalCase**. Не вводить отдельные «говорящие» имена файлов по смыслу содержимого (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts` и т.п.) — так теряется связь с компонентом и плодятся одноразовые названия.
+**File name prefix = public component name** (as in `ComponentName.tsx` in that folder), in **PascalCase**. Do not introduce separate "descriptive" file names by content meaning (`analysisPreparationIconMap.ts`, `buildAnalysisIdToNameMap.ts`, etc.) — that breaks the link to the component and creates one-off names.
 
-**Суффикс по роли:**
+**Role suffix:**
 
-| Суффикс | Назначение | Примеры содержимого |
-|--------|------------|---------------------|
-| `ComponentName.data.ts` | Статические данные и конфигурация для UI | мапы `id → иконка/лейбл`, константы списков, таблицы соответствий для отображения |
-| `ComponentName.utils.ts` | Чистые функции без React | форматирование, предобработка пропсов/данных для рендера, `build…`/`map…`‑хелперы |
-| `ComponentName.hooks.ts` | Хуки, используемые только этим блоком | локальные `use…` (если не вынесены в `src/ui/hooks/**`) |
+| Suffix | Purpose | Content examples |
+|--------|---------|------------------|
+| `ComponentName.data.ts` | Static data and UI configuration | `id → icon/label` maps, list constants, display lookup tables |
+| `ComponentName.utils.ts` | Pure non-React functions | formatting, prop/data preprocessing for render, `build…`/`map…` helpers |
+| `ComponentName.hooks.ts` | Hooks used only by this block | local `use…` (if not moved to `src/ui/hooks/**`) |
 
-- Несколько констант/мапов или несколько функций — **по-прежнему один** `.data.ts` и один `.utils.ts`, не дробить по «темам» отдельными файлами без веской причины (размер, разные зоны ответственности на уровне подкомпонентов).
-- Если логика принадлежит **подкомпоненту** в подпапке (`components/Child/Child.tsx`), те же правила применяются к **`Child.data.ts`**, **`Child.utils.ts`** относительно этого подкомпонента.
-- Тесты для утилит и данных — рядом в `__tests__/` или с суффиксом `.test.ts`, согласно `tests-unit.mdc`, с тем же префиксом (`RequestForAnalysisRecommendations.utils.test.ts` и т.д.).
+- Multiple constants/maps or multiple functions — still **one** `.data.ts` and one `.utils.ts`; do not split by "topic" into separate files without good reason (size, different responsibility at subcomponent level).
+- If logic belongs to a **subcomponent** in a subfolder (`components/Child/Child.tsx`), the same rules apply to **`Child.data.ts`**, **`Child.utils.ts`** for that subcomponent.
+- Tests for utilities and data — nearby in `__tests__/` or with `.test.ts` suffix per `tests-unit.mdc`, same prefix (`RequestForAnalysisRecommendations.utils.test.ts`, etc.).
 
-# Стили и дизайн‑токены
+# Styles and design tokens
 
-- **Корневой** styled в соседнем `styles` — экспорт **`Root`**; в JSX: `<s.Root>` при `import * as s from './styles'`. Вложенные — `Title`, `List` и т.д. Не `Container`/`Wrapper` для единственной обёртки.
-- **Запрещено** импортировать `styles` другого компонента (`../Other/styles`, `../../styles`). Разрешено: `./styles`, общие примитивы из `@/ui/components/...` или пакетов дизайн-системы.
-- Порядок CSS / `styled` — Stylelint idiomatic-order: `css-property-order-stylelint.mdc` (грузится на `styles.ts` / `.css`).
-- Для визуала использовать **тот стек стилей и токенов, который уже в проекте** (переменные, тема, общие классы, дизайн‑пакет).
-- Избегать:
-  - inline‑стилей, кроме простых случаев;
-  - дублирования оформления, уже закрытого общими примитивами;
-  - «магических» литералов (`#xxxxxx`, произвольные `17px` / `23px`), если в проекте есть токены или масштаб.
-- Если подходящего токена нет — локальный примитив **в одном месте** с последующим выравниванием под систему дизайна при возможности.
+- **Root** styled export in adjacent `styles` — **`Root`**; in JSX: `<s.Root>` with `import * as s from './styles'`. Nested — `Title`, `List`, etc. Not `Container`/`Wrapper` for a single wrapper.
+- **Forbidden** to import another component's `styles` (`../Other/styles`, `../../styles`). Allowed: `./styles`, shared primitives from `@/ui/components/...` or design-system packages.
+- CSS / `styled` order — Stylelint idiomatic-order: `css-property-order-stylelint.mdc` (loads on `styles.ts` / `.css`).
+- For visuals use **the style stack and tokens already in the project** (variables, theme, shared classes, design package).
+- Avoid:
+  - inline styles except simple cases;
+  - duplicating styling already covered by shared primitives;
+  - "magic" literals (`#xxxxxx`, arbitrary `17px` / `23px`) when the project has tokens or scale.
+- If no suitable token exists — a local primitive **in one place**, aligned with the design system when possible.
 
-# Пропсы и типизация
+# Props and typing
 
-- **Не передавать пропы в компоненты через spread** (`<Foo {...x} />`). Только явные атрибуты; подробности и исключения — `no-props-spread.mdc` (в `app/src/ui` это дополнительно ловит ESLint).
-- Описывать пропсы через `type Props = { ... }` или `interface Props { ... }`.
-- Не использовать `any`; при необходимости:
-  - обобщения (`<T>`), `unknown`, тип‑предикаты и user‑defined type guards.
-- Для доменных сущностей использовать типы из `@/types` (и enum из `@/types/enums`), а не описывать их заново (`public-imports.mdc`).
+- **Do not pass props via spread** (`<Foo {...x} />`). Only explicit attributes; details and exceptions — `no-props-spread.mdc` (in `app/src/ui` ESLint catches this too).
+- Describe props with `type Props = { ... }` or `interface Props { ... }`.
+- Do not use `any`; when needed:
+  - generics (`<T>`), `unknown`, type predicates and user-defined type guards.
+- For domain entities use types from `@/types` (and enums from `@/types/enums`), not redefined locally (`public-imports.mdc`).
 
-# Логика и side effects
+# Logic and side effects
 
-- Side effects и асинхронщина:
-  - по возможности выносить в store (thunk‑и, middleware) или в отдельные хуки.
-- Компоненты не должны:
-  - напрямую знать детали API (URL, структура DTO);
-  - заниматься маппингом "сырых" DTO — только доменные типы;
-  - содержать нетривиальные вычисления и преобразования данных (булевы флаги, сложная склейка строк, агрегаты и т.п.). В большинстве случаев данные для отображения должны быть подготовлены на этапах маппинга/подготовки данных (API -> доменная модель -> store), а компоненты использовать уже готовые поля.
+- Side effects and async:
+  - when possible, move to store (thunks, middleware) or dedicated hooks.
+- Components must not:
+  - know API details directly (URL, DTO shape);
+  - map "raw" DTOs — only domain types;
+  - contain non-trivial computations and data transforms (boolean flags, complex string concatenation, aggregates, etc.). In most cases display data should be prepared at mapping/preparation stages (API → domain model → store), and components use ready fields.
 
-# Тестирование UI
+# UI testing
 
-- Для нетривиальных компонентов добавлять тесты:
-  - **Testing Library** для React, как принято в проекте;
-  - проверять поведение и бизнес‑правила, а не конкретные CSS‑классы.
-- В тестах ориентироваться на текст, роли и aria‑атрибуты.
+- For non-trivial components add tests:
+  - **Testing Library** for React as adopted in the project;
+  - verify behavior and business rules, not specific CSS classes.
+- In tests prefer text, roles, and aria attributes.
 ## Incorrect
 
 ```tsx

package/presets/cursor/next/rules/reference-features.mdc

@@ -1,5 +1,5 @@
 ---
-description: Эталонные фичи репозитория — копировать структуру при реализации новых задач. Заполните пути после init в целевом репо.
+description: Repository reference features — copy structure when implementing new tasks. Fill paths after init in the target repo.
 globs:
   - app/src/ui/**/*
   - app/src/store/**/*
@@ -10,40 +10,40 @@ alwaysApply: false
 
 <!-- shared-core: architecture/reference-features.template.md -->
 
-# Эталонные фичи (reference features)
+# Reference features
 
 ## Stack notes
 
-Перед реализацией найди фичу того же типа и **повтори её структуру**, не изобретая новую организацию файлов.
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
 
 Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
 
-## Таблица эталонов
+## Reference table
 
-Замени **TBD** на реальные пути после договорённости в команде (или при `ai-rules init` в целевом репо):
+Replace **TBD** with real paths after team agreement (or on `ai-rules init` in the target repo):
 
-| Слой | Эталон | Что копировать |
-|------|--------|----------------|
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
 | UI page | **TBD** `app/src/ui/pages/<Example>/` | `components/`, `*.data.ts`, `styles.ts`, barrel |
 | Store slice | **TBD** `app/src/store/slices/<example>/` | slice, thunks, selectors, types |
 | API service | **TBD** `app/src/api/services/<example>/` | service, mappers, barrel |
 | Types module | **TBD** `app/src/types/<example>/` | domain types, JSDoc, barrel export |
-| Unit tests | **TBD** рядом с эталонным mapper/service | `*.spec.ts`, describe/it naming |
+| Unit tests | **TBD** next to the reference mapper/service | `*.spec.ts`, describe/it naming |
 | E2E area | **TBD** `app/__tests__/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
 
-## Как использовать
+## How to use
 
-1. Определи затронутые слои из `decomposition.md` или задачи.
-2. Открой эталон из таблицы (после заполнения путей).
-3. Зеркаль именование, порядок файлов, паттерны импортов и тестов.
-4. Если эталона нет — выбери **самую близкую** существующую фичу того же слоя и зафиксируй выбор в handoff.
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature of the same layer and record the choice in the handoff.
 
 ## Living conventions
 
 Post-init gotchas / patterns / decisions: **`.cursor/team/conventions.md`** (and the twin tool path if both Cursor and Claude are installed). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
 
-## Связанные правила
+## Related rules
 
-- `code-quality-and-refactoring.mdc` — повторять паттерны, не deep-import.
-- `feature-delivery-workflow.mdc` — порядок слоёв.
-- skill `feature-delivery` — end-to-end сценарий.
+- `code-quality-and-refactoring.mdc` — repeat patterns, no deep-import.
+- `feature-delivery-workflow.mdc` — layer order.
+- skill `feature-delivery` — end-to-end scenario.

package/presets/cursor/next/rules/store-rtk.mdc

@@ -1,69 +1,69 @@
 ---
-description: Redux Toolkit и состояние приложения
+description: Redux Toolkit and application state
 globs: app/src/store/**/*.ts
 alwaysApply: false
 impact: HIGH
 ---
 
-# Общие принципы
-
-- Использовать **Redux Toolkit**:
-  - `createSlice`, `createAsyncThunk`, RTK Query (если используется).
-- Хранить в store **доменные модели**, не "сырые" DTO из API.
-- Все вычисления и преобразования данных (включая вычисляемые поля, булевые флаги, агрегаты, человеко‑читаемые строки и т.п.) должны выполняться **между ответом API и записью в store** — в мапперах или отдельном слое подготовки данных. Store хранит уже подготовленную доменную модель.
-- Разделять:
-  - "серверное" состояние (данные из API) и
-  - локальное UI‑состояние (выбор/фильтры/флаги).
-
-# Структура слайсов
-
-- Каждый доменный модуль — свой слайс в `app/src/store/slices/**`.
-- Слайс экспортирует:
-  - `reducer` по умолчанию;
-  - `actions` именованным экспортом;
-  - селекторы `selectSomething(state: RootState): Type`.
-- Состояние:
-  - явный тип для state;
-  - аккуратная инициализация initialState.
-
-# Асинхронность и сайд‑эффекты
-
-- Асинхронные запросы:
-  - через `createAsyncThunk` или RTK Query.
-  - внутри thunk:
-    - вызывать API через сервисы, импортированные из `@/api` (**`public-imports.mdc`**);
-    - не вызывать HTTP‑клиент напрямую — только через эти сервисы.
-- Сайд‑эффекты (логирование, аналитика, работа с файлами):
-  - выносить в middleware (`app/src/store/middleware/**`) или специализированные слайсы.
-
-# Типизация
-
-- Использовать `RootState`, `AppDispatch` и типизированные хуки `useAppDispatch`, `useAppSelector` (если есть).
-- **HTTP и ошибки API**:
-  - не импортировать типы **сторонних HTTP‑библиотек**, которых нет в актуальных зависимостях и существующих слайсах (ориентир — **`package.json`** и соседние файлы);
-  - когда сервис возвращает **обёртку ответа** прикладного клиента — использовать **соответствующий тип из `@/types`** (как в barrel и в аналогичных thunk’ах);
-  - при ошибках после вызова сервиса — опираться на **тот же класс/контракт ошибки транспорта**, что использует общий клиент (из `@/types`), и разбирать тело/статус **по полям текущей реализации**, а не по воображаемому API;
-  - в **`catch`** предпочитать **`instanceof`** на класс ошибки транспорта из `@/types` (если он есть в коде) вместо голого `as`, когда это выразимо без шума (см. `no-type-assertion-as-import-export.mdc`).
-- Для сущностей:
-  - доменные типы (включая вычисляемые поля) определять в `app/src/types/**`, экспортировать через barrel и импортировать в слайсы из `@/types` как **источник правды** для структуры данных (`public-imports.mdc`);
-  - избегать дублирования описаний сущностей в нескольких местах.
-- **Граница домена**: в **state** хранить доменные модели; тип **обёртки ответа клиента** допустим как тип **возвращаемого значения thunk** или промежуточно до маппинга — без дублирования DTO в полях state без нужды (согласовано с `api-services.mdc` и `http-client.mdc`).
-
-# Тестирование слайсов
-
-- Для важных слайсов:
-  - тестировать редюсеры (инициализация, основные переходы состояний).
-  - тестировать селекторы (включая edge cases).
-- Thunk‑и:
-  - по возможности покрывать тестами с моками API‑слоя.
-
-# Требование к агенту
-
-При изменении/создании слайса:
-- Не класть логику API внутрь редюсеров/компонентов.
-- Строго типизировать state и actions.
-- Использовать единый стиль именования actions и селекторов, как в существующих слайсах.
-- При работе с ошибками и ответами HTTP опираться на **`http-client.mdc`** и контракты из `@/types`, а не на типы внешних HTTP‑библиотек вне зависимостей проекта.
+# General principles
+
+- Use **Redux Toolkit**:
+  - `createSlice`, `createAsyncThunk`, RTK Query (if used).
+- Store **domain models**, not "raw" DTOs from the API.
+- All data computations and transformations (including computed fields, boolean flags, aggregates, human-readable strings, etc.) must happen **between the API response and writing to store** — in mappers or a separate data-preparation layer. Store holds the prepared domain model.
+- Separate:
+  - "server" state (data from API) and
+  - local UI state (selection/filters/flags).
+
+# Slice structure
+
+- Each domain module — its own slice in `app/src/store/slices/**`.
+- A slice exports:
+  - default `reducer`;
+  - `actions` as named exports;
+  - selectors `selectSomething(state: RootState): Type`.
+- State:
+  - explicit state type;
+  - careful `initialState` initialization.
+
+# Async and side effects
+
+- Async requests:
+  - via `createAsyncThunk` or RTK Query.
+  - inside thunks:
+    - call API through services imported from `@/api` (**`public-imports.mdc`**);
+    - do not call the HTTP client directly — only through those services.
+- Side effects (logging, analytics, file handling):
+  - move to middleware (`app/src/store/middleware/**`) or specialized slices.
+
+# Typing
+
+- Use `RootState`, `AppDispatch`, and typed hooks `useAppDispatch`, `useAppSelector` (if present).
+- **HTTP and API errors**:
+  - do not import types from **third-party HTTP libraries** that are not in current dependencies and existing slices (guide — **`package.json`** and neighboring files);
+  - when a service returns the application client's **response wrapper** — use the **matching type from `@/types`** (as in the barrel and similar thunks);
+  - on errors after a service call — rely on the **same transport error class/contract** the shared client uses (from `@/types`), and parse body/status **by fields of the current implementation**, not an imagined API;
+  - in **`catch`**, prefer **`instanceof`** on the transport error class from `@/types` (if present in code) over bare `as`, when expressible without noise (see `no-type-assertion-as-import-export.mdc`).
+- For entities:
+  - define domain types (including computed fields) in `app/src/types/**`, export through barrel, import in slices from `@/types` as **source of truth** for data shape (`public-imports.mdc`);
+  - avoid duplicating entity descriptions in multiple places.
+- **Domain boundary**: in **state**, store domain models; the client **response wrapper** type is acceptable as a thunk **return type** or interim before mapping — without duplicating DTOs in state fields unnecessarily (aligned with `api-services.mdc` and `http-client.mdc`).
+
+# Slice testing
+
+- For important slices:
+  - test reducers (initialization, main state transitions).
+  - test selectors (including edge cases).
+- Thunks:
+  - cover with tests and API-layer mocks when possible.
+
+# Agent requirement
+
+When changing/creating a slice:
+- Do not put API logic inside reducers/components.
+- Strictly type state and actions.
+- Use a consistent naming style for actions and selectors, as in existing slices.
+- For HTTP errors and responses, rely on **`http-client.mdc`** and contracts from `@/types`, not external HTTP library types outside project dependencies.
 ## Incorrect
 
 ```ts

package/presets/cursor/next/rules/technical-retro.mdc

@@ -1,16 +1,16 @@
 ---
-description: Роль агента для проведения технического ретроспективы (retro) команды / спринта. On-demand — предпочтительнее slash-команда /technical-retro.
+description: Agent role for running a technical retrospective (retro) for a team / sprint. On-demand — prefer the /technical-retro slash command.
 alwaysApply: false
 ---
 
 <!-- shared-core: review/technical-retro.md -->
 
-# Техническое ретро — rule alias
+# Technical retro — rule alias
 
-Полный сценарий (включая блок **«Работа агентов»** для slug из team tasks) — в slash-команде:
+Full scenario (including the **“Agent work”** block for a slug from team tasks) lives in the slash command:
 
 **`commands/technical-retro.md`** → `/technical-retro`
 
 When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
 
-Используй rule только если command недоступен. Не дублируй содержимое command в ответе — следуй command-файлу и skill `technical-retro`.
+Use this rule only if the command is unavailable. Do not duplicate the command contents in the response — follow the command file and skill `technical-retro`.

package/presets/cursor/next/rules/tests-e2e-structure.mdc

@@ -1,51 +1,51 @@
 ---
-description: Структура e2e тестов и планов (Playwright)
+description: E2E test and plan structure (Playwright)
 globs: app/__tests__/e2e/**/*
 alwaysApply: false
 ---
 
-# Структура e2e в проекте
-
-- Папка e2e: `app/__tests__/e2e/**`.
-- Планы сценариев:
-  - `*.cases.md` файлы — **канонический источник сценариев**.
-- Тесты:
-  - `*.spec.ts` файлы — реализация сценариев на Playwright.
-- Общие утилиты и абстракции:
-  - `app/__tests__/e2e/_shared/**` — константы, fluent‑интерфейсы, хелперы.
-
-# Принципы
-
-- Каждый сценарий из `*.cases.md` должен иметь соответствующий тест (или набор тестов).
-- **Нельзя** ослаблять проверки в тестах, если это противоречит бизнес‑ожиданиям из планов.
-- Предпочтительно использовать:
-  - page‑objects (например, `OrderHistoryPage.ts`);
-  - общие хелперы из `_shared`.
-
-# Именование e2e‑тестов
-
-- Язык:
-  - все названия `test` / `it`, `describe`‑блоков и шагов в `*.cases.md` должны быть сформулированы **на русском языке**, описывая поведение и ожидаемый результат.
-- Формат заголовков e2e‑тестов (`test(...)` / `it(...)`):
-  - перед текстовым описанием сценария указывается **префикс с номером** в формате: `ПРЕФИКС-XXX Описание сценария`.
-  - `ПРЕФИКС` — аббревиатура из **первых букв слов** тестируемой сущности, записанная **латиницей в верхнем регистре**.
-    - пример: `OrderHistory` → `OH`, `BillingReport` → `BR`.
-  - `XXX` — порядковый номер теста **с тремя разрядами и лидирующими нулями**: `001`, `002`, `010`, `123` и т.д.
-  - пример полного названия e2e‑теста:
-    - `test('OH-001 Отображается список заказов', async ({ page }) => { ... })`
-  - внутри одной сущности (`ПРЕФИКС`) номера тестов должны образовывать **непротиворечивую последовательность**, без дубликатов номеров.
-
-# data-testid для e2e
-
-- **Приоритет селекторов:** `data-testid` для стабильных элементов; `getByRole` и `getByLabel` для форм и доступных элементов.
-- **Именование:** схема `{parent}__{element}` (например, `history-page__title`, `history-page__recognition-banner__attach-files-button`).
-- **Где добавлять:** на корневые контейнеры страниц и ключевые интерактивные элементы (кнопки, ссылки, поля), к которым обращаются page objects.
-- **При изменении UI:** обновлять data-testid в компонентах и соответствующие селекторы в page objects; сверять с `*.cases.md`.
-
-# Требование к агенту
-
-При добавлении/изменении e2e‑тестов:
-- Сначала смотреть соответствующий `*.cases.md` и синхронизировать названия сценариев.
-- Размещать спеки рядом с планами в той же директории.
-- Переиспользовать общие page‑objects и хелперы, а не копировать селекторы напрямую в каждый тест.
-
+# E2E structure in the project
+
+- E2E folder: `app/__tests__/e2e/**`.
+- Scenario plans:
+  - `*.cases.md` files — **canonical source of scenarios**.
+- Tests:
+  - `*.spec.ts` files — Playwright scenario implementations.
+- Shared utilities and abstractions:
+  - `app/__tests__/e2e/_shared/**` — constants, fluent interfaces, helpers.
+
+# Principles
+
+- Every scenario from `*.cases.md` must have a corresponding test (or set of tests).
+- **Do not** weaken assertions in tests if that contradicts business expectations from the plans.
+- Prefer:
+  - page objects (for example, `OrderHistoryPage.ts`);
+  - shared helpers from `_shared`.
+
+# E2E test naming
+
+- Language:
+  - in consumer apps, `test` / `it`, `describe` block titles, and steps in `*.cases.md` **may use the project locale** (often Russian) — phrasing behavior and expected outcome;
+  - when the repo ESLint or team convention requires Russian titles, follow that; otherwise use clear English business phrases.
+- E2E test title format (`test(...)` / `it(...)`):
+  - before the scenario description, include a **numbered prefix** in the form: `PREFIX-XXX Scenario description`.
+  - `PREFIX` — abbreviation from the **first letters of words** in the entity under test, written **in Latin uppercase**.
+    - example: `OrderHistory` → `OH`, `BillingReport` → `BR`.
+  - `XXX` — sequential test number **with three digits and leading zeros**: `001`, `002`, `010`, `123`, etc.
+  - full e2e test title example (Russian locale in consumer app):
+    - `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+  - within one entity (`PREFIX`), test numbers must form a **consistent sequence** with no duplicate numbers.
+
+# data-testid for e2e
+
+- **Selector priority:** `data-testid` for stable elements; `getByRole` and `getByLabel` for forms and accessible elements.
+- **Naming:** `{parent}__{element}` scheme (for example, `history-page__title`, `history-page__recognition-banner__attach-files-button`).
+- **Where to add:** on page root containers and key interactive elements (buttons, links, fields) that page objects target.
+- **When changing UI:** update data-testid in components and matching selectors in page objects; cross-check with `*.cases.md`.
+
+# Agent requirement
+
+When adding/changing e2e tests:
+- First read the matching `*.cases.md` and sync scenario titles.
+- Place specs next to plans in the same directory.
+- Reuse shared page objects and helpers instead of copying selectors directly into every test.