@bonesofspring/ai-rules 0.2.12 → 0.2.14

package/presets/claude/svelte/rules/architecture/layer-barrel-exports.md

@@ -0,0 +1,73 @@
+---
+description: Двухуровневые barrel-экспорты для слоёв с регламентированным public API
+paths:
+  - **/index.ts
+---
+
+# Barrel-экспорты слоёв с public API
+
+## Когда применять
+
+Для **любого слоя** (каталога, пакета, bounded context), у которого:
+
+- есть **корневой barrel** — единая точка импорта для внешних потребителей;
+- deep-импорты внутрь слоя **запрещены** снаружи (ESLint `no-restricted-imports`, правила `public-imports.mdc`).
+
+Примеры alias/entry point в разных проектах: `@/api`, `@/types`, `@/core`, `@/store`, `packages/foo`.
+
+## Два уровня barrel
+
+1. **Локальный** — `index.ts` модуля/фичи внутри слоя.
+2. **Корневой public API** — barrel слоя (например `src/<layer>/index.ts`).
+
+**Внутри** слоя — относительные импорты и пути между подмодулями. **Снаружи** — только корневой barrel и **явно разрешённые** вторичные entry points (если зафиксированы в правилах проекта, напр. `@/types/enums`).
+
+## Что реэкспортировать наружу
+
+Только символы, которые **должны быть доступны** потребителям слоя: публичные функции/сервисы/фасады, типы контракта, константы и helpers, нужные другим слоям или тестам.
+
+**Не реэкспортировать:** внутренние адаптеры, мапперы, детали транспорта, промежуточные объекты для сборки фасада внутри слоя.
+
+Группировка в корневом barrel — **по конвенции репозитория** (ориентир — соседние модули того же слоя).
+
+## Чеклист агента (обязателен)
+
+При добавлении или существенном расширении **модуля внутри регламентированного слоя**:
+
+1. Определить слой, его **корневой barrel** и доп. entry points (`public-imports.mdc`).
+2. Создать/обновить **локальный** `index.ts` — только публичные символы.
+3. Если в слое есть **фасад/агрегатор** (`*ApiService.ts`, `rootReducer`, …) — подключить модуль там.
+4. Добавить **реэкспорт** новых публичных символов в **корневой barrel** слоя.
+5. **Проверка:** grep по имени символа или пути `./<Module>` в корневом barrel; снаружи слоя нет deep-импортов.
+
+Модуль **не готов**, пока чеклист не пройден.
+
+## Как найти регламентированные слои в репозитории
+
+1. Правила `public-imports.mdc` в `.cursor/rules/`.
+2. ESLint `no-restricted-imports` — паттерны `@/<layer>/*` с исключением barrel.
+3. `architecture-boundaries.mdc`, README проекта.
+
+## В этом репозитории
+
+| Слой | Корневой barrel | Правило импортов |
+|------|-------------------|------------------|
+| API | `api/index.ts` | `public-imports.mdc` |
+| Types | `types/index.ts` | `public-imports.mdc` (+ `@/types/enums`) |
+| Core | `core/index.ts` | ESLint: `@/core/index` |
+
+Иллюстрация двух уровней (API): локальный `services/.../<Feature>/index.ts` → фасад `*ApiService.ts` → `api/index.ts`.
+## Incorrect
+
+```ts
+// api/index.ts — leaking internals
+export { mapCardResponse } from './services/CardsApi/cardResponseMappers'
+export { rawCardsClient } from './clients/rawCardsClient'
+```
+
+## Correct
+
+```ts
+// api/index.ts — public facade only
+export { cardsApi } from './services/CardsApi'
+```

package/presets/claude/svelte/rules/architecture/public-imports.md

@@ -0,0 +1,43 @@
+---
+description: Импорт доменных типов и API только через публичные barrels ($lib/types, $lib/api)
+paths:
+  - src/lib/components/**/*
+  - src/lib/stores/**/*
+  - src/lib/**/*
+  - src/routes/**/*
+  - src/lib/types/**/*
+  - src/lib/api/**/*
+---
+
+# Публичные импорты (`$lib/types`, `$lib/api`)
+
+Preferred alias: **`$lib`**. Accept **`@/`** if consumer vite/tsconfig maps it. Respect `$app/*` / `$env/*` — do not invent modules.
+
+## `$lib/types` (or `@/types`)
+
+- Публичный API типов — barrel `src/lib/types/index.ts`; снаружи слоя — только `$lib/types` / `@/types`.
+- Запрещено обходить barrel deep-импортами внутренних файлов типов (кроме project enum convention if present).
+- Внутри `src/lib/types/**` — относительные импорты.
+
+```typescript
+// ✅
+import type { TUserProfile } from '$lib/types'
+
+// ❌
+import type { TUserProfile } from '$lib/types/User.types'
+```
+
+## `$lib/api` (or `@/api`)
+
+- Публичный API — barrel `src/lib/api/index.ts`. Вне `src/lib/api/**` — только `$lib/api` / `@/api`.
+- Внутри слоя — относительные импорты и `$lib/api/services/**` / `$lib/clients/**` as neighbors do.
+
+```typescript
+// ✅
+import { ordersApi } from '$lib/api'
+
+// ❌
+import { ordersApi } from '$lib/api/services/orders/orders.service'
+```
+
+Новые публичные символы — реэкспорт в barrel по **`layer-barrel-exports`**.

package/presets/claude/svelte/rules/architecture/reference-features.md

@@ -0,0 +1,50 @@
+---
+description: Эталонные фичи репозитория — копировать структуру при реализации новых задач. Заполните пути после init в целевом репо.
+paths:
+  - src/lib/components/**/*
+  - src/lib/stores/**/*
+  - src/lib/api/**/*
+  - src/lib/types/**/*
+  - src/routes/**/*
+---
+
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Эталонные фичи (reference features)
+
+## Stack notes
+
+Перед реализацией найди фичу того же типа и **повтори её структуру**, не изобретая новую организацию файлов.
+
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+
+## Таблица эталонов
+
+Замени **TBD** на реальные пути после договорённости в команде (или при `ai-rules init` в целевом репо):
+
+| Слой | Эталон | Что копировать |
+|------|--------|----------------|
+| UI route / page | **TBD** `src/routes/<example>/` | `+page.svelte`, `+page.ts`, layout nesting |
+| UI component | **TBD** `src/lib/components/<Example>/` | `.svelte`, styles, barrel |
+| Store | **TBD** `src/lib/stores/<example>.ts` | writable/derived or runes module, actions |
+| API service | **TBD** `src/lib/api/services/<example>/` | service, mappers, barrel |
+| Types module | **TBD** `src/lib/types/<example>/` | domain types, JSDoc, barrel export |
+| Unit tests | **TBD** рядом с эталонным mapper/service | `*.spec.ts`, describe/it naming |
+| E2E area | **TBD** `tests/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
+
+## Как использовать
+
+1. Определи затронутые слои из `decomposition.md` или задачи.
+2. Открой эталон из таблицы (после заполнения путей).
+3. Зеркаль именование, порядок файлов, паттерны импортов и тестов.
+4. Если эталона нет — выбери **самую близкую** существующую фичу того же слоя и зафиксируй выбор в 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.
+
+## Связанные правила
+
+- `code-quality-and-refactoring.mdc` — повторять паттерны, не deep-import.
+- `feature-delivery-workflow.mdc` — порядок слоёв.
+- skill `feature-delivery` — end-to-end сценарий.

package/presets/claude/svelte/rules/stack/README.md

@@ -0,0 +1,12 @@
+# Stack (SvelteKit, Svelte 5, TypeScript)
+
+Правила уровня фреймворка и языка.
+
+| Файл | Содержание | Загрузка |
+|------|------------|----------|
+| `svelte-app-core.md` | Стек, структура `src/routes/**` / `src/lib/**`, слои | session start |
+| `svelte-script-conventions.md` | `<script lang="ts">` conventions | `paths: **/*.{svelte,ts}` |
+| `no-type-assertion.md` | Ограничение `as` на границах модулей | on-demand |
+| `navigation-router-ui.md` | Навигация в UI-компонентах (slim) | `paths: src/routes/**,src/hooks.server.ts,src/lib/components/**` |
+| `navigation-router.md` | Полный аудит стека навигации (SvelteKit file-based routing) | `paths: src/routes/**,src/hooks.server.ts,svelte.config.*` |
+| `types-jsdoc.md` | JSDoc в `types` | `paths: types/**/*.ts` |

package/presets/claude/svelte/rules/stack/navigation-router-ui.md

@@ -0,0 +1,26 @@
+---
+description: SvelteKit link patterns in UI — a href, active state, prefetch
+paths:
+  - src/lib/components/**/*
+  - src/routes/**/*
+---
+
+# Навигация (UI)
+
+- Prefer native **`<a href="…">`** (and design-system Link wrappers that render anchors).
+- Active state: follow repo pattern (`page.url`, `$app/state` / `$app/stores` as version allows — verify).
+- Prefetch: use Kit data-sveltekit-* attributes / patterns already in the repo — do not invent.
+- Do not use `next/link`, `<NuxtLink>`, or `RouterLink` as defaults in this preset.
+- Programmatic navigation from UI handlers → `goto` (`navigation-router-stack`).
+
+## Incorrect
+
+```svelte
+<a on:click|preventDefault={() => location.href = '/x'}>Go</a>
+```
+
+## Correct
+
+```svelte
+<a href="/x">Go</a>
+```

package/presets/claude/svelte/rules/stack/navigation-router.md

@@ -0,0 +1,41 @@
+---
+description: SvelteKit navigation APIs — $app/navigation, goto, invalidate
+paths:
+  - src/routes/**/*
+  - svelte.config.*
+---
+
+# Навигация (stack)
+
+Для этого пресета канон — **SvelteKit** (`svelte-app-core`, `sveltekit-routing`).
+
+## Проверить в репо
+
+1. `package.json` workspace с `svelte.config.*` — `@sveltejs/kit` / `svelte` majors.
+2. Как уже навигируют соседи: `goto`, `invalidate`, `beforeNavigate`, `<a href>`, wrappers.
+3. Не подмешивать Next (`next/navigation`) или Nuxt (`navigateTo`, `<NuxtLink>`) по умолчанию.
+
+## API
+
+| Need | Prefer |
+|------|--------|
+| Programmatic navigate | `goto` from `$app/navigation` |
+| Refresh load data | `invalidate` / `invalidateAll` |
+| Guards | `beforeNavigate` / `afterNavigate` |
+| Links in UI | see `navigation-router-ui` |
+
+Verify exports against installed `@sveltejs/kit` — mark `// VERIFY` if unsure (`svelte-sveltekit-anti-hallucination`).
+
+## Incorrect
+
+```ts
+import { useRouter } from 'next/navigation'
+await navigateTo('/items')
+```
+
+## Correct
+
+```ts
+import { goto } from '$app/navigation'
+await goto('/items')
+```

package/presets/claude/svelte/rules/stack/no-type-assertion.md

@@ -0,0 +1,59 @@
+---
+description: Избегать приведения типов через as на границах модулей (импорт/экспорт)
+paths:
+  - api/**/*
+  - src/lib/stores/**/*
+  - types/**/*
+---
+
+# Не использовать `as` для приведения типов при экспорте и импорте (кроме необходимых случаев)
+
+## О чём речь
+
+Речь о **type assertion** в TypeScript: выражение вида `значение as Тип`.
+
+**Не относится к правилу** (это не assertion, а синтаксис модулей):
+
+- переименование при экспорте: `export { foo as bar }`, `export { default as Baz } from '...'`;
+- переименование при импорте: `import { foo as bar } from '...'`;
+- `import type { Foo as Bar }` — алиас типа в импорте типов.
+
+## Требование
+
+- На **публичной границе модуля** (то, что **экспортируется** из файла / barrel, и то, что сразу **присваивается импортированным символам** с принудительным приведением) **не использовать** `as Тип` для «подгонки» типов, если можно обойтись нормальной типизацией.
+
+## Предпочитать вместо `as`
+
+- явную аннотацию: `const x: T = ...` / `function f(): T`;
+- **дженерики** у функций и классов;
+- **`satisfies`** (когда нужно проверить совместимость без сужения до `any`);
+- сужение **`unknown`** после проверки (type guards, `zod` и т.п.);
+- правку **исходных типов/DTO/мапперов**, а не assertion на выходе.
+
+## Когда `as` допустим
+
+- взаимодействие с **не типизированными** или некорректно типизированными внешними модулями, где нет разумной альтернативы;
+- узкие места после **валидации** данных, если типовый гард всё ещё не выразить без шума (предпочтительно всё же guard/`satisfies`);
+- **`as const`** — когда нужны литеральные типы и широкий вывод ломает контракт (это отдельный механизм; применять по делу, не как замену типизации API).
+- блок **`catch (error)`** после вызова HTTP через общий клиент: по возможности сужать через **`instanceof`** на **класс ошибки транспорта** из `@/types` (какой именно — по существующей реализации) и работать с уже суженным типом; голый **`as` к тому же типу** — только если `instanceof` недоступен (иной источник выброса) и осознанно.
+
+## Примеры
+
+```typescript
+// ❌ Плохо: assertion на экспортируемом API
+export const config = loadRaw() as AppConfig
+
+// ✅ Лучше: аннотация + проверка или маппер
+export const config: AppConfig = mapToAppConfig(loadRaw())
+
+// ❌ Плохо: сразу после импорта «ломаем» тип
+import { getData } from './api'
+export const data = getData() as MyDto[]
+
+// ✅ Лучше: типизировать getData / обернуть типобезопасной функцией
+```
+
+## Требование к агенту
+
+При ревью и генерации кода **не добавлять** новые `as Тип` на экспортируемые сущности и на цепочку import → export без явной необходимости; по возможности исправлять контракт типов в источнике.
+- В слайсах и сервисах при обработке ошибок API сначала рассматривать **`instanceof`** на класс ошибки транспорта из `@/types` по образцу существующего кода (`http-client.mdc`, `store-svelte.mdc`).

package/presets/claude/svelte/rules/stack/svelte-app-core.md

@@ -0,0 +1,44 @@
+---
+description: Базовые принципы, стек и архитектура SvelteKit приложения (preset)
+---
+
+# Стек и окружение
+
+Конкретные версии — **из `package.json` и конфигов целевого репозитория**. Рамка preset: SvelteKit, Svelte 5 (primary), TypeScript; runner/e2e/mocks/UI/APM — как заведено в репо.
+
+# Структура проекта
+
+| Путь | Назначение |
+|------|------------|
+| `src/routes/**` | Routes, layouts, load, form actions (`+page`, `+layout`, `+server`) |
+| `src/lib/components/**` | UI components (`.svelte`) |
+| `src/lib/**` | Facades / utils (no Vue-style `composables/` tree) |
+| `src/lib/stores/**` | Svelte stores + shared runes modules |
+| `src/lib/api/**` | Client services + mappers (barrel) |
+| `src/lib/clients/**` | HTTP (`fetch` wrapper) |
+| `src/hooks.server.ts` / `src/hooks.client.ts` | App hooks |
+| `src/lib/types/**` | Domain types (barrel) |
+| `tests/e2e/**` | Playwright e2e |
+
+**Aliases:** prefer `$lib`; respect `$app/*` / `$env/*` (не изобретать символы); accept `@/` если настроен. Scripts cwd — **корень SvelteKit** (где `svelte.config.*`), не Next-обёртка `app/`.
+
+# Архитектурные слои
+
+| Слой | Каталог | Детали |
+|------|---------|--------|
+| UI | `src/routes/**`, `src/lib/components/**` | `svelte-ui`, `architecture-boundaries-ui` |
+| Facades | `src/lib/**` | thin orchestration; no raw HTTP |
+| Store | `src/lib/stores/**` | `store-svelte` — writable/derived/readable + runes |
+| API | `src/lib/api/**` | `api-services`, `http-client` |
+| HTTP | `src/lib/clients/**` | wrap `fetch` |
+| Server | `+server.ts`, hooks | `security-sveltekit`; not a substitute for `src/lib/api/**` |
+| Types | `src/lib/types/**` | `public-imports`, `types-jsdoc` |
+
+Границы — **`architecture-boundaries`**. Импорты `$lib/types`, `$lib/api` (или `@/…` если aliased) — **`public-imports`**. **Запрещено:** RTK / Pinia / stems `store-rtk` / `store-pinia`, React/RSC, Vue/Nuxt defaults, пути `app/src/**` / `pages/**` / `composables/**` как канон.
+
+# Работа агента
+
+- Архитектура и импорты: `architecture-boundaries`, `public-imports`
+- Фичи: `feature-delivery-workflow` + skill `feature-delivery`
+- После правок: **вызвать** `post-change-lint` (requestable); менеджер пакетов: `package-manager`
+- Копировать паттерны соседей; предпочитать `unknown` вместо `any`

package/presets/claude/svelte/rules/stack/svelte-script-conventions.md

@@ -0,0 +1,33 @@
+---
+description: Svelte script conventions — lang=ts, runes primary, follow neighbors
+paths:
+  - "**/*.{svelte,ts}"
+---
+
+# Svelte script conventions
+
+- In `.svelte`: prefer `<script lang="ts">` (or project dual-script pattern if neighbors use it).
+- **Svelte 5 primary:** `$state` / `$derived` / `$effect` / `$props` / snippets for new code.
+- **Legacy secondary:** `svelte/store` writable/derived when neighbors use them — do not rewrite unrelated modules to runes in a drive-by.
+- Keep `<script>` focused: UI bindings + thin orchestration; HTTP only via `$lib/api` / store actions.
+- Prefer `unknown` over `any`; narrow before use.
+- Do not invent Options-API / Vue `<script setup>` patterns in this preset.
+- Arrow vs function: follow local neighbors; no blanket rewrite.
+
+## Incorrect
+
+```svelte
+<script>
+  // no lang=ts in a TS codebase; Vue setup APIs
+  import { ref } from 'vue'
+  const count = ref(0)
+</script>
+```
+
+## Correct
+
+```svelte
+<script lang="ts">
+  let count = $state(0)
+</script>
+```

package/presets/claude/svelte/rules/stack/sveltekit-routing.md

@@ -0,0 +1,40 @@
+---
+description: SvelteKit file-based routing, layouts, load, form actions
+paths:
+  - src/routes/**/*
+  - svelte.config.*
+---
+
+# SvelteKit routing
+
+Canonical layout: **SvelteKit `src/`** — `src/routes/**`.  
+Flat (no-`src/`) layouts exist; **do not** default globs/examples to them or to Next `app/src/**` / Nuxt `pages/**`.
+
+## Routing
+
+- File-based routes: `+page.svelte`, `+layout.svelte`, `+error.svelte`.
+- Load: `+page.ts` / `+page.server.ts` / `+layout.ts` / `+layout.server.ts` — verify signatures against installed `@sveltejs/kit`.
+- Form actions in `+page.server.ts`; progressive enhancement via `$app/forms` `enhance` when used in repo.
+- API / BFF: `+server.ts`; app hooks in `src/hooks.server.ts` / `src/hooks.client.ts` — see `security-sveltekit`.
+- Navigation: `<a href>`, `goto`, `invalidate`, `beforeNavigate`, `$app/navigation` — not `next/navigation`, not `navigateTo` / `<NuxtLink>`.
+
+## Data on pages
+
+- Prefer `$lib/api` services + mappers for domain mapping; `load` may use event `fetch` for same-origin SSR cookie forwarding.
+- Client orchestration via `store-svelte` (stores / runes).
+- Secrets only via `$env/static/private` / server modules — never `$env/static/private` in client components.
+
+## Incorrect
+
+```ts
+import { useRouter } from 'next/navigation'
+import { navigateTo } from '#app'
+```
+
+## Correct
+
+```ts
+import { goto } from '$app/navigation'
+
+await goto('/items')
+```

package/presets/claude/svelte/rules/stack/types-jsdoc.md

@@ -0,0 +1,42 @@
+---
+description: Стиль JSDoc для доменных и транспортных типов в types
+paths:
+  - src/lib/types/**/*.ts
+---
+
+# Документация типов в `types`
+
+При добавлении или существенном изменении типов в этом слое **следовать уже принятому в репозитории стилю JSDoc** (см. примеры: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+
+## Язык и форма
+
+- Текст комментариев — **на русском**, кратко и по делу: что означает тип или поле в предметной области или в контракте с API.
+- **Не опираться** на теги в духе `@param`, `@returns`, `@see`, `@deprecated` для описания типов — в этом слое они **не используются**; достаточно обычного текста в `/** … */`.
+
+## Экспортируемый `type` / `interface`
+
+- Сразу **перед объявлением** — блок `/** … */`.
+- Если нужно пояснить источник данных, ограничения или неочевидности — **второй абзац** в том же блоке (в JSDoc для абзаца — пустая строка между строками текста).
+- Для **вложенных** объектов в том же файле каждый такой тип документируется отдельным блоком над своим объявлением.
+
+## Поля
+
+- У **каждого** публичного свойства — **однострочный** `/** … */` на строке непосредственно **над** полем.
+- Если поле **не приходит с бэкенда «как есть»**, а вычисляется или дополняется на фронте (маппер, селектор, UI) — начать описание с префикса **`[computed]`** (как в `TUserProfile`, типах плана лечения).
+- Для форматов данных указывать это **в тексте**: например дата `YYYY-MM-DD`, пример отображаемой строки в кавычках.
+
+## Классы и прочие объявления
+
+- Для **классов** (например ошибки транспорта) при изменении публичного API — краткий блок над классом и **комментарии к публичным полям** по тем же правилам, что у свойств интерфейса.
+
+## `enum`
+
+- В `enums.ts` исторически часто **без JSDoc** на каждом члене; для новых enum допустимо короткое описание **над самим enum**, если назначение неочевидно из имени. Подписи для UI — как принято, через объекты `*Names` рядом с enum.
+
+## Практика для агента
+
+- Добавляя новый тип или поле, **не оставлять** новые публичные поля без пояснения, если смысл не равен имени на 100%.
+- Правя файл, где уже есть такие комментарии, **поддерживать тот же стиль**, а не смешивать с англоязычными или «теговыми» блоками.
+- Не раздувать комментарии: одна-две фразы на тип, одна строка на поле — норма; исключение — действительно сложная доменная оговорка.
+
+См. также импорты и barrel: `public-imports.mdc`.

package/presets/claude/svelte/rules/testing/README.md

@@ -0,0 +1,11 @@
+# Testing
+
+Unit, e2e, Playwright agents.
+
+| Файл | Содержание | Загрузка |
+|------|------------|----------|
+| `playwright-agents.md` | Planner / generator / healer — структура e2e | session start |
+| `tests-unit.md` | Unit/integration, именование на русском | `paths: **/*.spec.*`, `*.test.*` |
+| `tests-e2e-structure.md` | `*.cases.md`, page objects, data-testid | `paths: tests/e2e/**` |
+
+См. также `.claude/agents/playwright-test-*.md` после `ai-rules init`.

package/presets/claude/svelte/rules/testing/playwright-agents.md

@@ -0,0 +1,80 @@
+---
+description: Playwright Agents (planner/generator/healer) configuration for e2e structure in tests/e2e
+paths:
+  - tests/e2e/**/*
+---
+
+# Playwright Agents in this project
+
+In this repository, Playwright Agents (planner, generator, healer) **must follow the existing e2e structure**:
+
+- **Test directory**: `tests/e2e`
+- **Test plans (specs)**: `*.cases.md` files under `tests/e2e/**`
+- **Executable tests**: `*.spec.ts` files under `tests/e2e/**`
+- **Seed test**: `tests/e2e/seed.spec.ts`
+
+Do **not** introduce separate top-level `specs/` and `tests/` folders for real test coverage. Those may be used only as temporary sandboxes if explicitly requested.
+
+## Planner (test plans)
+
+When acting as a **Planner** (or working with the Playwright planner agent):
+
+- **Treat `*.cases.md` as the canonical test plan files**, equivalent to Playwright's `specs/*.md`.
+- **Location**:
+  - For a feature/domain, use the corresponding `*.cases.md` file under `tests/e2e`, e.g.:
+    - `tests/e2e/OrderHistory/order-history.cases.md`
+    - `tests/e2e/BillingReport/invoice-list.cases.md`
+- **Content requirements**:
+  - Group scenarios by feature and subfeature using headings.
+  - For each scenario include:
+    - clear title,
+    - preconditions,
+    - ordered steps,
+    - expected results.
+  - Write in concise business language, but precise enough for automatic test generation.
+- **Seed**:
+  - Assume environment is prepared by `tests/e2e/seed.spec.ts` (login, baseURL, mocks, etc.).
+
+When asked to "generate a test plan" for a feature, **create or update the appropriate `*.cases.md` file in `tests/e2e/**`**, not in a separate `specs/` folder.
+
+## Generator (tests from plans)
+
+When acting as a **Generator** (or working with the Playwright generator agent):
+
+- **Source of truth for scenarios**:
+  - Use the relevant `*.cases.md` file under `tests/e2e/**` as the test plan.
+- **Target for tests**:
+  - Generate or update `*.spec.ts` files under the same folder, e.g.:
+    - plan: `tests/e2e/OrderHistory/order-history.cases.md`
+    - tests: `tests/e2e/OrderHistory/order-history.spec.ts` (or additional `*.spec.ts` in that folder if needed).
+- **Structure**:
+  - Use `test.describe` to group by top-level plan sections (feature / user flow).
+  - Use `test(...)` titles that match scenario names from the plan.
+  - Prefer Page Object and fluent interfaces that already exist in this project, for example:
+    - `tests/e2e/OrderHistory/OrderHistoryPage.ts`
+    - shared helpers under `tests/e2e/_shared/`.
+- **Seed**:
+  - If a seed test is needed, use `tests/e2e/seed.spec.ts` as the reference for environment setup.
+
+Do **not** generate Playwright tests into a separate `tests/` folder by default. Keep all e2e tests under `tests/e2e/**` to respect project conventions.
+
+## Healer (fixing tests)
+
+When acting as a **Healer** (or working with the Playwright healer agent):
+
+- Operate only on `*.spec.ts` files under `tests/e2e/**`.
+- Use `*.cases.md` in the same folder as **documentation of the intended behavior**:
+  - Do not weaken or change business assertions in tests in a way that conflicts with the corresponding `*.cases.md`.
+  - Prefer updating locators, waits, and flow details to match the UI while keeping the scenario semantics intact.
+- When multiple specs are involved, prioritize:
+  - the spec file in the same folder as the failing test,
+  - then shared utilities in `tests/e2e/_shared/`.
+
+Healer should keep tests aligned with the existing test plans (`*.cases.md`) and with the page objects and helpers already used in the project.
+
+
+## Stack notes (SvelteKit)
+
+- E2E root: `tests/e2e/`.
+- Default baseURL: `http://localhost:5173`.
+- Prefer Playwright `webServer` → `vite dev` or `vite build && vite preview`.

package/presets/claude/svelte/rules/testing/tests-e2e-structure.md

@@ -0,0 +1,51 @@
+---
+description: Структура e2e тестов и планов (Playwright)
+paths:
+  - tests/e2e/**/*
+---
+
+# Структура e2e в проекте
+
+- Папка e2e: `tests/e2e/**`.
+- Планы сценариев:
+  - `*.cases.md` файлы — **канонический источник сценариев**.
+- Тесты:
+  - `*.spec.ts` файлы — реализация сценариев на Playwright.
+- Общие утилиты и абстракции:
+  - `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 и хелперы, а не копировать селекторы напрямую в каждый тест.
+