@bonesofspring/ai-rules 0.2.13 → 0.2.15

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

@@ -0,0 +1,73 @@
+---
+description: Two-level barrel exports for layers with a regulated public API
+paths:
+  - **/index.ts
+---
+
+# Barrel exports for layers with a public API
+
+## When to apply
+
+For **any layer** (directory, package, bounded context) that has:
+
+- a **root barrel** — single import point for external consumers;
+- deep imports into the layer **forbidden** from outside (ESLint `no-restricted-imports`, `public-imports.mdc` rules).
+
+Example alias/entry points across projects: `@/api`, `@/types`, `@/core`, `@/store`, `packages/foo`.
+
+## Two barrel levels
+
+1. **Local** — `index.ts` of a module/feature inside the layer.
+2. **Root public API** — layer barrel (e.g. `src/<layer>/index.ts`).
+
+**Inside** the layer — relative imports and paths between submodules. **Outside** — only the root barrel and **explicitly allowed** secondary entry points (if fixed in project rules, e.g. `@/types/enums`).
+
+## What to re-export outward
+
+Only symbols that **must be available** to layer consumers: public functions/services/facades, contract types, constants and helpers needed by other layers or tests.
+
+**Do not re-export:** internal adapters, mappers, transport details, intermediate objects used to assemble a facade inside the layer.
+
+Grouping in the root barrel — **per repository convention** (orient on neighboring modules of the same layer).
+
+## Agent checklist (required)
+
+When adding or substantially extending a **module inside a regulated layer**:
+
+1. Identify the layer, its **root barrel**, and extra entry points (`public-imports.mdc`).
+2. Create/update the **local** `index.ts` — public symbols only.
+3. If the layer has a **facade/aggregator** (`*ApiService.ts`, `rootReducer`, …) — wire the module there.
+4. Add a **re-export** of new public symbols in the layer’s **root barrel**.
+5. **Verify:** grep for the symbol name or path `./<Module>` in the root barrel; no deep imports from outside the layer.
+
+The module is **not ready** until the checklist passes.
+
+## How to find regulated layers in the repository
+
+1. `public-imports.mdc` rules in `.claude/rules/`.
+2. ESLint `no-restricted-imports` — `@/<layer>/*` patterns with barrel exception.
+3. `architecture-boundaries.mdc`, project README.
+
+## In this repository
+
+| Layer | Root barrel | Import rule |
+|-------|-------------|-------------|
+| API | `api/index.ts` | `public-imports.mdc` |
+| Types | `types/index.ts` | `public-imports.mdc` (+ `@/types/enums`) |
+| Core | `core/index.ts` | ESLint: `@/core/index` |
+
+Two-level illustration (API): local `services/.../<Feature>/index.ts` → facade `*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: Import domain types and API only through public barrels ($lib/types, $lib/api)
+paths:
+  - src/lib/components/**/*
+  - src/lib/stores/**/*
+  - src/lib/**/*
+  - src/routes/**/*
+  - src/lib/types/**/*
+  - src/lib/api/**/*
+---
+
+# Public imports (`$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`)
+
+- Public types API — barrel `src/lib/types/index.ts`; outside the layer — only `$lib/types` / `@/types`.
+- Forbidden to bypass the barrel via deep imports of internal type files (except a project enum convention if present).
+- Inside `src/lib/types/**` — relative imports.
+
+```typescript
+// ✅
+import type { TUserProfile } from '$lib/types'
+
+// ❌
+import type { TUserProfile } from '$lib/types/User.types'
+```
+
+## `$lib/api` (or `@/api`)
+
+- Public API — barrel `src/lib/api/index.ts`. Outside `src/lib/api/**` — only `$lib/api` / `@/api`.
+- Inside the layer — relative imports and `$lib/api/services/**` / `$lib/clients/**` as neighbors do.
+
+```typescript
+// ✅
+import { ordersApi } from '$lib/api'
+
+// ❌
+import { ordersApi } from '$lib/api/services/orders/orders.service'
+```
+
+New public symbols — re-export in the barrel per **`layer-barrel-exports`**.

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

@@ -0,0 +1,50 @@
+---
+description: Repository reference features — mirror their structure when implementing new work. Fill in paths after init in the target repo.
+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
+
+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
+
+Replace **TBD** with real paths after team agreement (or on `ai-rules init` in the target repo):
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| 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** next to the reference mapper/service | `*.spec.ts`, describe/it naming |
+| E2E area | **TBD** `tests/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
+
+## How to use
+
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled in).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature in the same layer and record the choice in the handoff.
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.claude/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` — repeat patterns; no deep-import.
+- `feature-delivery-workflow.mdc` — layer order.
+- skill `feature-delivery` — end-to-end scenario.

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

@@ -0,0 +1,12 @@
+# Stack (SvelteKit, Svelte 5, TypeScript)
+
+Framework- and language-level rules.
+
+| File | Contents | Loading |
+|------|----------|---------|
+| `svelte-app-core.md` | Stack, `src/routes/**` / `src/lib/**` structure, layers | session start |
+| `svelte-script-conventions.md` | `<script lang="ts">` conventions | `paths: **/*.{svelte,ts}` |
+| `no-type-assertion.md` | Limit `as` on module boundaries | on-demand |
+| `navigation-router-ui.md` | Navigation in UI components (slim) | `paths: src/routes/**,src/hooks.server.ts,src/lib/components/**` |
+| `navigation-router.md` | Full navigation stack audit (SvelteKit file-based routing) | `paths: src/routes/**,src/hooks.server.ts,svelte.config.*` |
+| `types-jsdoc.md` | JSDoc in `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/**/*
+---
+
+# Navigation (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.*
+---
+
+# Navigation (stack)
+
+For this preset the canon is **SvelteKit** (`svelte-app-core`, `sveltekit-routing`).
+
+## Check in the repo
+
+1. `package.json` workspace with `svelte.config.*` — `@sveltejs/kit` / `svelte` majors.
+2. How neighbors already navigate: `goto`, `invalidate`, `beforeNavigate`, `<a href>`, wrappers.
+3. Do not mix in Next (`next/navigation`) or Nuxt (`navigateTo`, `<NuxtLink>`) by default.
+
+## 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: Avoid type assertions via as at module boundaries (import/export)
+paths:
+  - api/**/*
+  - src/lib/stores/**/*
+  - types/**/*
+---
+
+# Do not use `as` for type assertion on export and import (except necessary cases)
+
+## What this is about
+
+This is about TypeScript **type assertion**: expressions like `value as Type`.
+
+**Not covered by this rule** (not assertion — module syntax):
+
+- rename on export: `export { foo as bar }`, `export { default as Baz } from '...'`;
+- rename on import: `import { foo as bar } from '...'`;
+- `import type { Foo as Bar }` — type alias in a type import.
+
+## Requirement
+
+- On the **public module boundary** (what is **exported** from a file / barrel, and what is immediately **assigned from imported symbols** with a forced cast) **do not use** `as Type` to “force-fit” types when normal typing would work.
+
+## Prefer instead of `as`
+
+- an explicit annotation: `const x: T = ...` / `function f(): T`;
+- **generics** on functions and classes;
+- **`satisfies`** (when you need to check compatibility without narrowing to `any`);
+- narrowing **`unknown`** after checks (type guards, `zod`, etc.);
+- fixing **source types/DTOs/mappers**, not an assertion on the way out.
+
+## When `as` is allowed
+
+- interaction with **untyped** or incorrectly typed external modules where there is no reasonable alternative;
+- narrow spots after **validation**, if a type guard still cannot be expressed without noise (prefer guard/`satisfies` anyway);
+- **`as const`** — when literal types are needed and wide inference breaks the contract (a separate mechanism; use on purpose, not as a substitute for API typing).
+- a **`catch (error)`** block after HTTP via the shared client: prefer narrowing with **`instanceof`** on the **transport error class** from `@/types` (which one — follow the existing implementation) and work with the narrowed type; bare **`as` to the same type** — only if `instanceof` is unavailable (different throw source) and deliberately.
+
+## Examples
+
+```typescript
+// ❌ Bad: assertion on exported API
+export const config = loadRaw() as AppConfig
+
+// ✅ Better: annotation + check or mapper
+export const config: AppConfig = mapToAppConfig(loadRaw())
+
+// ❌ Bad: immediately after import we “break” the type
+import { getData } from './api'
+export const data = getData() as MyDto[]
+
+// ✅ Better: type getData / wrap with a type-safe function
+```
+
+## Agent requirement
+
+On review and code generation **do not add** new `as Type` on exported entities and on the import → export chain without clear need; when possible fix the type contract at the source.
+- In slices and services when handling API errors, first consider **`instanceof`** on the transport error class from `@/types` following existing code (`http-client.mdc`, `store-svelte.mdc`).

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

@@ -0,0 +1,44 @@
+---
+description: Core principles, stack, and architecture for a SvelteKit app (preset)
+---
+
+# Stack and environment
+
+Concrete versions — **from `package.json` and configs in the target repository**. Preset frame: SvelteKit, Svelte 5 (primary), TypeScript; runner/e2e/mocks/UI/APM — as established in the repo.
+
+# Project structure
+
+| Path | Purpose |
+|------|---------|
+| `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/*` (do not invent symbols); accept `@/` if configured. Scripts cwd — **SvelteKit root** (where `svelte.config.*` lives), not a Next-style `app/` wrapper.
+
+# Architectural layers
+
+| Layer | Directory | Details |
+|-------|-----------|---------|
+| 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` |
+
+Boundaries — **`architecture-boundaries`**. Imports `$lib/types`, `$lib/api` (or `@/…` if aliased) — **`public-imports`**. **Forbidden:** RTK / Pinia / stems `store-rtk` / `store-pinia`, React/RSC, Vue/Nuxt defaults, paths `app/src/**` / `pages/**` / `composables/**` as canon.
+
+# Agent work
+
+- Architecture and imports: `architecture-boundaries`, `public-imports`
+- Features: `feature-delivery-workflow` + skill `feature-delivery`
+- After edits: **invoke** `post-change-lint` (requestable); package manager: `package-manager`
+- Copy neighbor patterns; prefer `unknown` over `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 style for domain and transport types under types
+paths:
+  - src/lib/types/**/*.ts
+---
+
+# Type documentation in `types`
+
+When adding or substantially changing types in this layer **follow the JSDoc style already used in the repository** (see examples: `User.types.ts`, `Common.types.ts`, `ServerValidation.types.ts`, `TreatmentPlan/*.types.ts`).
+
+## Language and form
+
+- Comment text — **in Russian**, short and to the point: what the type or field means in the domain or API contract.
+- **Do not rely** on tags like `@param`, `@returns`, `@see`, `@deprecated` for type descriptions — they are **not used** in this layer; plain `/** … */` text is enough.
+
+## Exported `type` / `interface`
+
+- Immediately **before the declaration** — a `/** … */` block.
+- If you need to explain data source, constraints, or non-obvious bits — a **second paragraph** in the same block (blank line between paragraphs in JSDoc).
+- For **nested** objects in the same file, each such type gets its own block above its declaration.
+
+## Fields
+
+- Every **public** property — a **one-line** `/** … */` on the line immediately **above** the field.
+- If a field **does not come from the backend “as is”** but is computed or enriched on the frontend (mapper, selector, UI) — start the description with the **`[computed]`** prefix (as in `TUserProfile`, treatment-plan types).
+- For data formats, state that **in the text**: e.g. date `YYYY-MM-DD`, example display string in quotes.
+
+## Classes and other declarations
+
+- For **classes** (e.g. transport errors), when changing the public API — a short block above the class and **comments on public fields** by the same rules as interface properties.
+
+## `enum`
+
+- In `enums.ts` historically often **without JSDoc** on each member; for new enums a short description **above the enum itself** is OK if purpose is not obvious from the name. UI labels — as usual, via `*Names` objects next to the enum.
+
+## Agent practice
+
+- When adding a new type or field, **do not leave** new public fields unexplained if the meaning is not 100% equal to the name.
+- When editing a file that already has such comments, **keep the same style**, do not mix with English or “tag-style” blocks.
+- Do not inflate comments: one–two phrases per type, one line per field — normal; exception — a truly complex domain caveat.
+
+See also imports and barrel: `public-imports.mdc`.

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

@@ -0,0 +1,11 @@
+# Testing
+
+Unit, e2e, Playwright agents.
+
+| File | Contents | Loading |
+|------|----------|---------|
+| `playwright-agents.md` | Planner / generator / healer — e2e structure | session start |
+| `tests-unit.md` | Unit/integration; titles in Russian (locale convention) | `paths: **/*.spec.*`, `*.test.*` |
+| `tests-e2e-structure.md` | `*.cases.md`, page objects, data-testid | `paths: tests/e2e/**` |
+
+See also `.claude/agents/playwright-test-*.md` after `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,50 @@
+---
+description: Structure of e2e tests and plans (Playwright)
+paths:
+  - tests/e2e/**/*
+---
+
+# E2E structure in the project
+
+- E2E folder: `tests/e2e/**`.
+- Scenario plans:
+  - `*.cases.md` files — **canonical source of scenarios**.
+- Tests:
+  - `*.spec.ts` files — Playwright scenario implementation.
+- Shared utilities and abstractions:
+  - `tests/e2e/_shared/**` — constants, fluent interfaces, helpers.
+
+# Principles
+
+- Every scenario from `*.cases.md` must have a matching test (or set of tests).
+- **Do not** weaken assertions in tests if that contradicts business expectations from the plans.
+- Prefer:
+  - page objects (e.g. `OrderHistoryPage.ts`);
+  - shared helpers from `_shared`.
+
+# E2E test naming
+
+- Language:
+  - all `test` / `it` names, `describe` blocks, and steps in `*.cases.md` must be formulated **in Russian**, describing behavior and the expected result. <!-- i18n-keep: E5 -->
+- E2E title format (`test(...)` / `it(...)`):
+  - before the scenario description, put a **numbered prefix** in the form: `PREFIX-XXX Scenario description`.
+  - `PREFIX` — abbreviation from the **first letters of the words** of 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 title example:
+    - `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 -->
+  - within one entity (`PREFIX`), test numbers must form a **consistent sequence** without duplicate numbers.
+
+# data-testid for e2e
+
+- **Selector priority:** `data-testid` for stable elements; `getByRole` and `getByLabel` for forms and accessible elements.
+- **Naming:** scheme `{parent}__{element}` (e.g. `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 UI changes:** update data-testid in components and matching selectors in page objects; align with `*.cases.md`.
+
+# Agent requirement
+
+When adding/changing e2e tests:
+- First look at the matching `*.cases.md` and sync scenario names.
+- Place specs next to plans in the same directory.
+- Reuse shared page objects and helpers; do not copy selectors into every test.

package/presets/claude/svelte/rules/testing/tests-unit.md

@@ -0,0 +1,40 @@
+---
+description: Unit tests — Vitest + Testing Library Svelte; colocated *.spec.ts
+paths:
+  - "**/*.{spec,test}.ts"
+---
+
+# Shared testing rules
+
+- **File names:** new tests — **`*.spec.ts`**. Do not rename existing `*.test.ts` without a task.
+- **Runner:** Vitest (or as in the project). Components — **`@testing-library/svelte`** (not `@vue/test-utils`, not React Testing Library as default).
+- Assert **behavior**, not internals.
+- **`describe` / `it` naming:** formulate titles **in Russian**, each sentence capitalized (as with ESLint `jest/valid-title` if enabled). <!-- i18n-keep: E5 -->
+
+```typescript
+// ✅
+it('Возвращает пустой список. Пользователь не авторизован', () => {}) // <!-- i18n-keep: E5 -->
+
+// ❌
+it('Returns empty list when user is guest', () => {})
+```
+
+# Components
+
+- `render` from `@testing-library/svelte`.
+- Interactions: `userEvent` from `@testing-library/user-event` when that is the repo convention.
+
+# Isolation
+
+- Mock `$lib/api` / stores per neighbor patterns.
+- Do not mock the feature’s public contract without need.
+
+# HTTP / mappers
+
+- Changes to the shared HTTP client — behavior tests next to `src/lib/clients/**`.
+- DTO→domain mappers — unit tests for edge cases.
+
+# Placement
+
+- UI: neighboring `*.spec.ts` (no required `__tests__/` inside the component).
+- Other modules — as neighbors do.