@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/opencode/svelte/rules/reference-features.md

@@ -0,0 +1,82 @@
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+## Reference table
+
+Replace placeholders with **real** paths after `ai-rules init` / team agreement:
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI / Presentation | **TBD** | components, styles/data helpers, barrel |
+| State / ViewModel | **TBD** | slice/VM, selectors, types |
+| API / Data | **TBD** | service/repo, mappers, barrel |
+| Domain / Types | **TBD** | domain types, public export |
+| Unit tests | **TBD** | `*.spec` / XCTest naming |
+| E2E / UI tests | **TBD** | cases/plans, page objects / accessibility IDs |
+
+## How to use
+
+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
+
+After init the team maintains **local** gotchas, patterns, and decisions in a consumer-owned store (not in shared core and not only in root `AGENTS.md`):
+
+| Section | What to record |
+|---------|----------------|
+| Gotchas | Recurring traps, fragile spots, “do not do X in this repo” |
+| Patterns | Local patterns beyond the reference table |
+| Decisions | Short ADR links / product decisions that affect code |
+
+Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.md`). The file is **not** always-on.
+
+## Related rules
+
+- `code-quality-and-refactoring` — repeat patterns, no deep-import.
+- `feature-delivery-workflow` — layer order.
+- skill `feature-delivery` — end-to-end scenario.
+
+> Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.
+
+## 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: **`.ai.local/conventions.md`** (shared across tools; `.ai.local/team/**` is pipeline artifacts, not rules). 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/opencode/svelte/rules/security-sveltekit.md

@@ -0,0 +1,32 @@
+# Security (SvelteKit)
+
+## Secrets & env
+
+- Private secrets: `$env/static/private` / server-only modules — **never** import into client `.svelte` / universal modules that ship to browser.
+- Public config: `$env/static/public` (prefixed per project convention).
+- Do not commit `.env` with secrets; do not log tokens.
+
+## Server boundaries
+
+- `+server.ts`, `+page.server.ts`, `hooks.server.ts` may touch private env and privileged backends.
+- Do not import `.svelte` UI into server handlers by default.
+- Prefer `$lib/api` for domain client services; keep BFF thin.
+
+## XSS / HTML
+
+- Prefer text interpolation; `{@html …}` only with sanitized/trusted content.
+- Follow `svelte-a11y-coding` and eslint-plugin-svelte a11y where configured.
+
+## CSRF / forms
+
+- Prefer Kit form actions + progressive enhancement patterns already in the repo.
+- Validate/authorize on the server; never trust client-only checks for authz.
+
+## HTTP client
+
+- Use project `fetch` wrapper (`http-client`); forward cookies via `load`/`event.fetch` for same-origin SSR when required.
+- Do not put credentials in public env or client bundles.
+
+## Agent discipline
+
+- If unsure whether a module is server-only, check filename (`.server.ts`), imports, and siblings — mark `// VERIFY` rather than guessing.

package/presets/opencode/svelte/rules/store-svelte.md

@@ -0,0 +1,59 @@
+# Shared principles
+
+- **Primary (Svelte 5):** runes in `.svelte` / `.svelte.ts` — `$state`, `$derived`, `$effect`, `$props`, `$bindable` as applicable.
+- **Secondary (legacy / shared):** `writable` / `derived` / `readable` from `svelte/store` when neighbors do so or for shared state outside runes — “follow neighbors”.
+- Store / shared modules hold **domain models**, not raw DTOs.
+- DTO → domain mapping — in `src/lib/api/**` (or server mappers) **before** writing to store/runes.
+- UI-only flags may stay local in the component (`$state`) if that is the repo convention.
+
+# Forbidden in this preset
+
+- RTK / Redux: `createSlice`, `createAsyncThunk`, RTK Query, `useDispatch` / `useSelector`, stem `store-rtk`.
+- Pinia / Vuex: `defineStore`, stem `store-pinia`.
+- Raw `fetch` from the store bypassing `$lib/api` services (except narrow documented repo exceptions).
+- Importing `$state` / runes from invented packages — only Svelte runtime / documented APIs for the installed major.
+
+# Structure
+
+- Domain module — file under `src/lib/stores/**` (e.g. `src/lib/stores/profile.ts` or `profile.svelte.ts`).
+- Export explicit store factories / rune modules; names as neighbors use.
+- Actions / functions call services from `$lib/api` (`public-imports`).
+
+# Async
+
+```ts
+// Incorrect — raw HTTP + DTO in state
+import { writable } from 'svelte/store'
+export const profile = writable(null)
+export async function loadProfile() {
+  profile.set(await fetch('/api/profile').then((r) => r.json()))
+}
+
+// Correct
+import { writable } from 'svelte/store'
+import { profileApi } from '$lib/api'
+import type { Profile } from '$lib/types'
+
+export const profile = writable<Profile | null>(null)
+
+export async function loadProfile() {
+  profile.set(await profileApi.getProfile())
+}
+```
+
+# Typing and errors
+
+- Domain types from `$lib/types` (or `@/types` if aliased).
+- Transport errors — contracts from types / the accepted client class (`http-client`).
+- In UI: `$profile` / subscribe / `$derived` — follow neighbors.
+
+# Testing
+
+- Cover important stores / rune modules (init, transitions, actions with mocked API).
+- Unit: Vitest; mock `$lib/api` services.
+
+# Agent requirement
+
+- Do not put HTTP/transport in components.
+- Strictly type state/actions.
+- Follow the style of neighboring stores / runes modules.

package/presets/opencode/svelte/rules/svelte-a11y-coding.md

@@ -0,0 +1,21 @@
+# Svelte a11y coding
+
+- Prefer semantic HTML (`button`, `a`, `label`, landmarks) over clickable `div`/`span`.
+- Interactive elements need keyboard support and visible focus — follow neighbors and design system.
+- Images: meaningful `alt` (or empty alt for decorative).
+- Forms: associate labels; surface errors accessibly.
+- Respect `eslint-plugin-svelte` a11y rules when configured; do not blanket-disable without why.
+- Dynamic UI (dialogs, menus): focus trap / restore patterns already used in the repo — do not invent a second a11y stack.
+- Pair with `svelte-ui` and `architecture-boundaries-ui`.
+
+## Incorrect
+
+```svelte
+<div onclick={submit}>Save</div>
+```
+
+## Correct
+
+```svelte
+<button type="submit">Save</button>
+```

package/presets/opencode/svelte/rules/svelte-app-core.md

@@ -0,0 +1,40 @@
+# 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/opencode/svelte/rules/svelte-script-conventions.md

@@ -0,0 +1,27 @@
+# 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/opencode/svelte/rules/svelte-sveltekit-anti-hallucination.md

@@ -0,0 +1,63 @@
+# Svelte / SvelteKit anti-hallucination
+
+These rows **OVERRIDE** generation for the listed patterns. Before inventing an import, load helper, or store API: verify against `package.json` (installed majors), `svelte.config.*`, and sibling files. If unsure, mark `// VERIFY: lib.symbol @ version` and surface the uncertainty — do not silently stub.
+
+## 1. Phantom `$app/*` / Kit modules
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Invented `$app/foo`, `$app/router`, `$app/auth` | Real `$app/navigation`, `$app/stores`, `$app/forms`, `$app/environment`, `$app/paths`, `$app/state` **for installed major** |
+| Importing Next `next/navigation` / `next/link` | `$app/navigation`, `<a href>` |
+| `navigateTo`, `<NuxtLink>`, `#imports` auto-import phantoms | Kit APIs + explicit imports that exist in repo |
+| Invented `@sveltejs/kit` helpers not in docs/lockfile | Documented Kit exports for installed version |
+
+## 2. Load / page data signatures
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Invented `PageLoad` / `LayoutServerLoad` shapes from blogs | Types from `./$types` generated for the route; match siblings |
+| Returning random keys without `data` contract | Follow existing `+page(.server).ts` return shapes |
+| Calling React `getServerSideProps` / Nuxt `useAsyncData` in Kit | `load` / form actions / `$lib/api` |
+
+## 3. Form actions / enhance
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Phantom `enhance` option bags siblings never use | `$app/forms` `enhance` patterns from neighbors + Kit docs |
+| Invented `fail` / `redirect` import paths | `@sveltejs/kit` exports verified for major |
+| Posting secrets from client form without server action | `+page.server.ts` actions + `$env` discipline |
+
+## 4. `$env/*` misuse
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `$env/static/private` / private dynamic env in `.svelte` client | Private env only in `.server.ts` / hooks / `+server.ts` |
+| Invented `$env/secret` | `$env/static/public`, `$env/static/private`, `$env/dynamic/*` as documented |
+
+## 5. Runes vs stores
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `import { $state } from 'svelte/store'` (wrong) | Runes are language/runtime — follow Svelte 5 docs / neighbors |
+| Pinia `defineStore` / RTK `createSlice` | `store-svelte` — writable/derived/readable or runes modules |
+| Invented `createRuneStore` helpers | Patterns already in `src/lib/stores/**` |
+
+## 6. Cross-stack APIs (banned as defaults)
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| React hooks (`useEffect`, `useState` from `react`) | Svelte reactivity / runes / stores |
+| RSC / `next/navigation` / `next/image` | Kit routes + `$app/*` |
+| Vue/Nuxt: `ref`, `defineStore`, `useFetch`, `navigateTo` | Svelte / Kit equivalents above |
+
+## 7. Paths / gates / spreads
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| E2E under `app/__tests__/e2e` | `tests/e2e/**` |
+| Required script named `typecheck` / `type-check` | Package script **`check`** (`svelte-kit sync && svelte-check`) |
+| Unlimited `{...props}` / `$$restProps` as default | Explicit props (`no-rest-props-spread`) |
+| Server-only modules imported into client components | Keep private env / Node APIs in `.server.ts` |
+| Vue-style auto-import of missing symbols | Explicit `$lib` / `$app` imports that exist |
+
+When a row conflicts with a verified sibling pattern in this repo, **the sibling wins** — update this banlist in a preset PR rather than inventing a third path.

package/presets/opencode/svelte/rules/svelte-ui.md

@@ -0,0 +1,38 @@
+# Svelte UI (SvelteKit)
+
+- Prefer **`.svelte` SFC** with `<script lang="ts">` (`svelte-script-conventions`).
+- Explicit props (`$props()` / typed props); no mass `{...props}` / `$$restProps` (`no-rest-props-spread`).
+- Svelte 5: snippets / `{@render …}` preferred for new code; legacy slots OK when following neighbors.
+- Styles: scoped `<style>` / tokens — as neighbors do; property order — `css-property-order-stylelint`.
+- Data: read stores / runes / `load` data; **do not** call HTTP from `.svelte` — only via `$lib/api` / store actions.
+- Navigation: `<a href>`, `goto`, `invalidate`, `$app/navigation` — not `next/link`, not `<NuxtLink>`, not `navigateTo`.
+- A11y: `svelte-a11y-coding`.
+- UI boundaries: `architecture-boundaries-ui` — no DTO in markup; map in `src/lib/api/**`.
+
+# Conditional rendering
+
+- Prefer **decomposition over conditionals**: markup with several `{#if}` / `{:else if}` / `{:else}` branches should become a thin parent that renders child components, not one growing block.
+- Keep the condition in the parent; children receive resolved props.
+- No nested ternaries in markup. For loading / empty / error, use dedicated `EmptyState` / `ErrorState` components or snippets.
+- A `variant` / `mode` prop that renders two unrelated layouts is **two** components, not one.
+
+## Incorrect
+
+```svelte
+<script lang="ts">
+  const data = await fetch('/api/items').then((r) => r.json())
+</script>
+```
+
+## Correct
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte'
+  import { loadItems } from '$lib/stores/items'
+
+  onMount(() => {
+    void loadItems()
+  })
+</script>
+```

package/presets/opencode/svelte/rules/sveltekit-routing.md

@@ -0,0 +1,33 @@
+# 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/opencode/svelte/rules/technical-retro.md

@@ -0,0 +1,11 @@
+<!-- shared-core: review/technical-retro.md -->
+
+# Technical retro — rule alias
+
+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.
+
+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/opencode/svelte/rules/tests-e2e-structure.md

@@ -0,0 +1,88 @@
+<!-- shared-core: testing/testing-principles.md -->
+
+# Testing principles
+
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
+
+## Behavior vs. implementation
+
+- Verify **behavior and business rules**, not implementation or internal details.
+
+## File naming
+
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
+
+## Runner and matchers
+
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
+
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
+
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
+
+## Isolation and mocks
+
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+
+## Coverage of cross-cutting modules
+
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
+
+## Data transformation coverage
+
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
+
+## Reuse fixtures over ad-hoc random data
+
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
+
+## E2E: one canonical scenario plan per feature
+
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
+
+## E2E: scenario ↔ test traceability
+
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## E2E: keep plans and selectors in sync with UI
+
+- When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
+
+## Stack notes
+
+- Runner: Playwright (`@playwright/test`).
+- E2E folder: `tests/e2e/**`.
+- Scenario plans: `*.cases.md` — canonical source.
+- Tests: `*.spec.ts` — Playwright implementations.
+- Shared utilities: `tests/e2e/_shared/**`.
+- **Russian-locale HARD policy:** all `test` / `it` titles, `describe` blocks, and `*.cases.md` steps MUST be in Russian, describing behavior + expected result. <!-- i18n-keep: E5 -->
+- `data-testid` priority: `data-testid` for stable; `getByRole` / `getByLabel` for forms.
+- `data-testid` naming scheme `{parent}__{element}` — example `history-page__title`, `history-page__recognition-banner__attach-files-button`.
+- `PREFIX-XXX` example: `OrderHistory` → `OH`, `BillingReport` → `BR`.
+- Russian example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed).
+- Page object example filename: `OrderHistoryPage.ts`.
+- Cross-reference: See also **`playwright-agents.mdc`**.
+- `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.

package/presets/opencode/svelte/rules/tests-unit.md

@@ -0,0 +1,83 @@
+<!-- shared-core: testing/testing-principles.md -->
+
+# Testing principles
+
+Stack-agnostic; concrete paths, runners, and selectors live in the stack adapter (`## Stack notes`).
+
+## Behavior vs. implementation
+
+- Verify **behavior and business rules**, not implementation or internal details.
+
+## File naming
+
+- For **new** tests use `*.spec.ts` / `*.spec.tsx`. Do not rename existing `*.test.ts` / `*.test.tsx` without a separate task (legacy).
+
+## Runner and matchers
+
+- Use the project's runner (Jest or Vitest are common); components — the project's Testing Library integration. Reuse existing matchers — no new micro-framework.
+
+## Test title locale
+
+- Consumer apps **may use the project locale** (often Russian) — clear business phrases stating what is checked and the expected outcome.
+- When ESLint enforces the locale (e.g. `jest/valid-title`): each sentence must start with a **capital letter** (including after `.`, `!`, `?`); a space after `.` followed by a lowercase letter is forbidden ("capital after period" violation).
+
+Good (Russian locale in consumer app):
+
+- `it('Возвращает пустой список. Пользователь не авторизован', () => {})` <!-- i18n-keep: E5 --> (Returns empty list. User is not authorized)
+
+Bad (no capital after period; or wrong locale for configured ESLint):
+
+- `it('Возвращает пустой список. пользователь не авторизован', () => {})` <!-- i18n-keep: E5 -->
+- `it('Returns empty list when user is guest', () => {})` (wrong locale if ESLint enforces Russian)
+
+## Isolation and mocks
+
+- Mock at the **public-contract boundary**; use the project's accepted HTTP/API/store mock approach. Do not mock what is part of the feature's public contract if that breaks the test's meaning.
+
+## Coverage of cross-cutting modules
+
+- When changing a **shared cross-cutting module** (e.g. HTTP client body parsing, headers, error / auth handling) — **update or add behavior tests** covering success, error, and edge branches relevant to the module under change.
+
+## Data transformation coverage
+
+- Data transformation functions with computed fields and branches must have unit tests covering edge cases (boundary values, missing fields, unexpected value combinations).
+
+## Reuse fixtures over ad-hoc random data
+
+- Prefer shared fixtures / handlers from the project's accepted mocks module; do not duplicate interfaces in tests. Use the API response types (DTO types) and the **target domain types** from the project's public type surface.
+
+## E2E: one canonical scenario plan per feature
+
+- For each feature keep a **single canonical scenario plan** (distinct from implementation specs; the stack adapter names the file — typically `*.cases.md`).
+
+## E2E: scenario ↔ test traceability
+
+- Every scenario has a corresponding test. **Do not weaken** assertions to match an outdated implementation — tests must reflect business expectations from the plan. Colocate plan and executable tests in the same directory.
+
+## E2E: page objects / shared helpers
+
+- Prefer page objects and shared helpers over scattered selectors and per-test setup duplication.
+
+## E2E: stable identifiers (PREFIX-XXX)
+
+- When scenarios need stable IDs, prefix the title with `PREFIX-XXX`: `PREFIX` = first letters of words in the entity under test (Latin uppercase); `XXX` = sequential number with three digits and leading zeros. Within one `PREFIX`, numbers must form a consistent sequence with no duplicates.
+- Example: `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed)
+
+## E2E: selector priority
+
+- Prefer role/label selectors for accessibility and forms; fall back to `data-testid` for stable elements. Use a **hierarchical naming convention** on page roots and key interactive elements (stack adapter defines the scheme — typically `{parent}__{element}`).
+
+## E2E: keep plans and selectors in sync with UI
+
+- When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
+
+## Stack notes
+
+- Runner: Vitest (default for SvelteKit).
+- Components: `render` from `@testing-library/svelte` (NOT `@vue/test-utils`, NOT React Testing Library as default).
+- `userEvent` from `@testing-library/user-event` when that is the repo convention.
+- HTTP-client behavior tests next to `src/lib/clients/**` (SvelteKit convention; no `app/`, no `src/app/`).
+- Mock `$lib/api` / stores per neighbor patterns.
+- DTO→domain mappers — unit tests for edge cases.
+- UI placement: sibling `*.spec.ts` in `src/lib/components` (no `__tests__/` inside the component folder).
+- `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.

package/presets/opencode/svelte/rules/types-jsdoc.md

@@ -0,0 +1,36 @@
+# 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.md`.