@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/presets/opencode/next/rules/product-specs.md

@@ -0,0 +1,56 @@
+<!-- shared-core: architecture/product-specs.md -->
+
+# Product specs (docs/specs)
+
+Product page/feature **behavior** specs live under the consumer repo `docs/specs/**`. This stem covers **discovery and presence** — not layer implementation order (see `feature-delivery-workflow`) and not code-structure mirroring (see `reference-features`).
+
+**Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
+
+**Pipeline `specMode`:** `consume` (this stem) · `generate` (authoring stem) · `none` (spike/research — skip INDEX row requirement; do not invent a dummy INDEX). Primary field: `brief.md` `## Spec mode`; optional `pipeline.json` `specMode`.
+
+## Modes (summary)
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
+| **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
+| **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+| **None** (`specMode: none`) | Spike / research / preset-only | Skip INDEX requirement and author mode; no dummy INDEX row |
+
+Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
+
+## Presence policy
+
+- If `specMode` is **`none`** → do **not** require an INDEX row; continue from brief/AC. Do not invent INDEX.
+- If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
+- If INDEX **exists** and `specMode` is not `none` → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+
+## Discovery algorithm
+
+1. Always start at `docs/specs/INDEX.md` when present (skip when `specMode: none`).
+2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
+3. Read the **linked page** spec and, when INDEX or page Related links it, the optional domain `feature.md`. Do **not** dump the whole `docs/specs/**` tree into the prompt — locator = those linked files.
+
+## Miss policy (INDEX present, row or file missing)
+
+- Record the gap in `open_questions` / handoff gaps.
+- Fall back to code discovery and consumer `.ai/context/**` when present.
+- **Do not invent** product behavior, states, interactions, or contracts.
+- Hard-fail / block only when the task’s acceptance criteria explicitly require a named spec that is absent (human/gate decision).
+
+## Authoring pointer
+
+Same-changeset INDEX updates, frontmatter v1, required body headings, templates, and conflict precedence live in **`product-specs-authoring`**. Do not paste the full checklist here.
+
+## Non-goals
+
+- Not a replacement for `.ai/context/**` (external AI Code Review glossary) or `reference-features` (file-layout mirror).
+- Not Tessl / an external host as primary SoT.
+- No stack filesystem path recipes in this core body — path examples belong only in adapter **Stack notes**.
+
+## Related
+
+- `product-specs-authoring` — generation modes, contracts, self-check.
+- Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
+- `reference-features` — code structure mirror (how to layout files), not product behavior.
+- Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.

package/presets/opencode/next/rules/public-imports.md

@@ -0,0 +1,50 @@
+# Public imports (`@/types`, `@/api`)
+
+**Collisions:** type imports — `@/types` section below; API outside `app/src/api/**` — `@/api` section below (mirrors ESLint `no-restricted-imports` in `app/eslint.config.mjs`).
+
+## `@/types`
+
+- **Public types API** — barrel `app/src/types/index.ts`; import types only as `@/types` (or `@/types/index`).
+- **Forbidden** to bypass the barrel: `@/types/<anything>`, except enums.
+- **Enums** — only `@/types/enums` / `@/types/enums.ts`.
+- Inside `app/src/types/**` — relative imports between layer files.
+
+```typescript
+// ✅
+import type { TUserProfile } from '@/types'
+import { SomeEnum } from '@/types/enums'
+
+// ❌
+import type { TUserProfile } from '@/types/User.types'
+```
+
+New public types — re-export in `app/src/types/index.ts` per **`layer-barrel-exports.md`**.
+
+## `@/api`
+
+- **Public API** — barrel `app/src/api/index.ts`. Outside `app/src/api/**` — only `import … from '@/api'` (or `@/api/index`).
+- **Forbidden** from outside the layer: `@/api/<anything>`, except `@/api/index`.
+- Inside `app/src/api/**` — relative imports and `@/api/services/**`, `@/api/clients/**`.
+
+```typescript
+// ✅ in store, UI, lib outside app/src/api
+import { MedcardApiService } from '@/api'
+
+// ❌ outside app/src/api
+import { MedcardApiService } from '@/api/services/MedcardApiService/MedcardApiService'
+```
+
+New public API symbols — re-export in `app/src/api/index.ts` per **`layer-barrel-exports.md`**.
+## Incorrect
+
+```ts
+import type { TUserProfile } from '@/types/User.types'
+import { OrdersApi } from '@/api/services/OrdersApi'
+```
+
+## Correct
+
+```ts
+import type { TUserProfile } from '@/types'
+import { ordersApi } from '@/api'
+```

package/presets/opencode/next/rules/react-a11y-coding.md

@@ -0,0 +1,31 @@
+# A11y when developing UI
+
+The reviewer (`accessibility-reviewer`) checks the diff; these rules apply **while writing** code.
+
+## Semantics and ARIA
+
+- Prefer **native elements** (`button`, `a`, `label`, `input`) over `div` with `onClick`.
+- **`role` / `aria-*`** — only when there is no native equivalent; do not duplicate what semantics already provide.
+- Headings — `h1`–`h6` hierarchy without skipping levels for styling.
+
+## Forms
+
+- Every input is associated with a **`label`** (`htmlFor` / `id` or wrapper).
+- Error messages — **`aria-describedby`**, `aria-invalid` on validation errors.
+- Submit vs button — explicit `type`.
+
+## Keyboard and focus
+
+- All interactive elements are **reachable via Tab** and activatable with Enter/Space where expected.
+- **Modals/drawers** — focus trap, return focus to trigger on close, Esc closes (if UX allows).
+- Do not remove visible **focus outline** without an accessible custom focus style.
+
+## Content
+
+- Images — **`alt`** (empty `alt` only for decorative images).
+- Icon buttons — **`aria-label`** or visually hidden text.
+- Dynamic updates — `aria-live` for critical status/error (use sparingly).
+
+## Verification
+
+- When unsure — devtools a11y tree or `accessibility-reviewer` in the pipeline for UI-heavy features.

package/presets/opencode/next/rules/react-next-anti-hallucination.md

@@ -0,0 +1,60 @@
+# React / Next / RTK anti-hallucination
+
+These rows **OVERRIDE** generation for the listed patterns. Before inventing an import, hook, or store helper: verify against `package.json` (installed majors) and sibling files in the same layer. If unsure, mark `// VERIFY: lib.symbol @ version` and surface the uncertainty — do not silently stub.
+
+App Router–specific rows (async `params` / `cookies()`, invented auth helpers, etc.) stay in **`next-app-router.md`**. This rule covers broader React / RTK / Next phantom imports and boundary mistakes across `app/**`.
+
+## 1. Phantom / wrong Next imports
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `import Head from 'next/head'` in App Router trees | Metadata API (`export const metadata` / `generateMetadata`) or project pattern |
+| `import { … } from 'next/document'` / `_app` / `_document` APIs in App Router repos | App Router `layout.tsx` / `template.tsx`; do not invent Pages Router entrypoints |
+| Invented paths: `next/server-actions`, `next/rsc`, `next/auth`, `next/cache/react` | Real exports from installed `next` (`next/server`, `next/cache`, `next/headers`, …) — check docs for **that** major |
+| `getServerSideProps` / `getStaticProps` / `getInitialProps` in `app/` routes | RSC data loaders, route handlers, or server actions — mirror sibling routes |
+| `import Image from 'next/image/legacy'` without verifying package | `next/image` (or repo’s established image helper); mark `VERIFY` if legacy path is intentional |
+
+## 2. RSC / client boundary
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `useAppSelector` / `useDispatch` / RTK hooks in a Server Component (no `'use client'`) | Client boundary component, or server data via `@/api` / loaders — see `next-app-core` |
+| `process.env.SECRET_*` / non-`NEXT_PUBLIC_` secrets in client bundles | Server-only env; client gets only `NEXT_PUBLIC_*` or values from a server action/API |
+| Passing non-serializable props (functions, class instances, store) from RSC → client | Plain data props; callbacks stay in client trees |
+| Importing a `'use client'` module that re-exports server-only secrets into the client graph | Keep secrets in server modules; split barrels so client never pulls them |
+
+## 3. React patterns
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Invented hooks from wrong packages (`useFormState` from `react-dom` when the repo uses a form lib; fake `use` from `react-redux`) | Copy import path from a sibling file; confirm symbol in installed React / React-DOM major |
+| Deprecated React APIs without version check (`ReactDOM.render`, `findDOMNode`, string refs, `defaultProps` on function components) | Current API for the installed React major (`createRoot`, function defaults, …) |
+| `import { useEffectEvent } from 'react'` (or similar) when `package.json` React may not ship it yet | Check React version first; else local pattern / mark `VERIFY` |
+| Phantom packages: `react-server-dom`, `@react/cache`, invented `@/hooks/useServerQuery` | Only packages in lockfile + public hooks already used in the repo |
+
+## 4. RTK / RTK Query phantoms
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Fake `createSlice` options (`extraReducers` as plain object without builder, invented `slice.injectEndpoints`) | RTK patterns from existing slices (`store-rtk.md`); builder callback for `extraReducers` |
+| Invented RTKQ helpers: `api.injectQuery`, `createApiEndpoint`, `useLazyGetX` without a matching `endpoints` definition | Endpoints defined on the real `createApi` instance; hooks generated from that API |
+| Deep / wrong store imports: `@/store/slices/foo/fooSlice` or `@/store/index` when public API is `@/store` | Public store barrel / typed hooks as in sibling UI (`public-imports.md`) |
+| Storing raw transport DTOs or inventing axios/fetch error shapes in slice state | Domain models + transport error types from `@/types` as in existing thunks |
+
+## 5. Navigation / data
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `import { useRouter } from 'next/router'` in App Router apps | `next/navigation` (`useRouter`, `usePathname`, `useSearchParams`) — see `navigation-router-stack.md` |
+| `Router.push` / Pages `withRouter` patterns in `app/` UI | App Router navigation helpers already used in `app/src/ui/**` |
+| Client `fetch` / raw HTTP from UI or `page.tsx` bypassing `@/api` | Services via `@/api` / established loaders (`api-services.md`, `http-client.md`) |
+| Invented `next/link` props that siblings never use (e.g. fake prefetch enums) | Match existing `<Link>` usage; verify against installed Next |
+
+## 6. Version drift
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Bleeding-edge Next/React APIs (“I saw it in a blog”) without checking `package.json` | Confirm major/minor in manifest + lockfile; copy a sibling that already compiles |
+| Assuming async `cookies()` / `headers()` / `params` behavior from a newer Next than installed | Follow **installed** Next + `next-app-router.md` table; mark `VERIFY` if majors differ across docs |
+
+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/next/rules/react-ui.md

@@ -0,0 +1,105 @@
+# General component rules
+
+- 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
+
+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).
+
+## Child components (`./components`)
+
+- 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`
+  - style files per project scheme;
+  - optional: `types.ts`, `ComponentName.hooks.ts` (see prefix rules below).
+
+## Adjacent helper modules (naming)
+
+**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:**
+
+| 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/**`) |
+
+- 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 — under the mirrored path `app/__tests__/unit/<rel>` per `tests-unit.md`, with the same prefix (`RequestForAnalysisRecommendations.utils.spec.ts`, etc.).
+
+# Styles and design tokens
+
+- **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.md` (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
+
+- **Do not pass props via spread** (`<Foo {...x} />`). Only explicit attributes; details and exceptions — `no-props-spread.md` (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.md`).
+
+# Logic and side effects
+
+- 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 testing
+
+- 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
+import { mapUserDto } from '@/api/services/UsersApi/userResponseMappers'
+
+export const UserBadge = ({ dto }: { dto: unknown }) => {
+  const user = mapUserDto(dto as any) // mapping + deep import in UI
+  return <span>{user.name}</span>
+}
+```
+
+## Correct
+
+```tsx
+import type { TUserProfile } from '@/types'
+
+export const UserBadge = ({ user }: { user: TUserProfile }) => {
+  return <span>{user.name}</span>
+}
+```

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

@@ -0,0 +1,45 @@
+<!-- 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 (`team/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**.

package/presets/opencode/next/rules/security-next.md

@@ -0,0 +1,45 @@
+# Security (Next.js)
+
+Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-review`.
+
+## Secrets and env
+
+- Never put service / secret keys in `NEXT_PUBLIC_*` or client bundles (`sk_`, private API keys, DB URLs).
+- Do not commit `.env*` with real secrets; use CI / secret manager patterns already in the repo.
+- Prefer server-only modules for privileged clients; do not import them into Client Components.
+
+## Auth and session
+
+- Enforce auth on the **server** (layouts, pages, Server Actions, route handlers) — not only Edge middleware.
+- Middleware may refresh sessions; do not treat middleware alone as authorization.
+- Prefer httpOnly secure cookies over `localStorage` for tokens when the repo pattern allows.
+- Never trust client-only session claims without a server verify step used by the project.
+
+## Mutations and input
+
+- Server Actions / route handlers: validate untrusted input at the edge (Zod or the repo’s schema pattern).
+- Prefer an explicit success/error response shape over throwing opaque errors to the client.
+- CSRF / origin checks — follow existing repo middleware and form patterns for state-changing requests.
+
+## XSS and output
+
+- Avoid `dangerouslySetInnerHTML` unless sanitized and unavoidable; prefer text nodes / safe components.
+- Sanitize or encode user-generated HTML/markdown before render.
+- Open redirects: validate redirect targets against an allowlist or same-origin paths.
+
+## Data exposure
+
+- Do not log tokens, passwords, or full PII in client or server logs.
+- Do not return full privileged records to the client — map to the minimum domain fields the UI needs.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Invented auth helpers not in `package.json` / codebase | Copy patterns from existing auth routes |
+| Putting secrets in `NEXT_PUBLIC_*` | Server-only env + server modules |
+| Auth only in middleware | Server `getUser` / session verify in layout/page/action |
+
+## Agent requirement
+
+On auth, forms, payments, or env changes — load this rule and `code-review-mr.md`. Route sensitive features through `security-reviewer`.

package/presets/opencode/next/rules/store-rtk.md

@@ -0,0 +1,78 @@
+# 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.md`**);
+    - 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.md`).
+- 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.md`);
+  - 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.md` and `http-client.md`).
+
+# 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.md`** and contracts from `@/types`, not external HTTP library types outside project dependencies.
+## Incorrect
+
+```ts
+export const loadProfile = createAsyncThunk('profile/load', async () => {
+  const res = await fetch('/api/profile')
+  return res.json() // raw DTO into slice
+})
+```
+
+## Correct
+
+```ts
+import { profileApi } from '@/api'
+
+export const loadProfile = createAsyncThunk('profile/load', async () => {
+  // service returns domain model already mapped
+  return profileApi.getProfile()
+})
+```

package/presets/opencode/next/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/next/rules/tests-e2e-structure.md

@@ -0,0 +1,72 @@
+<!-- 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.

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

@@ -0,0 +1,72 @@
+<!-- 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.