@bonesofspring/ai-rules 0.2.6 → 0.2.8

package/presets/cursor/java/rules/design-guidance.mdc

@@ -0,0 +1,112 @@
+---
+description: Design smells (Fowler) and curated GoF patterns for agents. Load when assessing structure, smells, or pattern fit.
+globs:
+  - "**/*.java"
+alwaysApply: false
+---
+
+<!-- shared-core: quality/design-guidance.md -->
+
+# Design guidance (smells & patterns)
+
+Словарь **code smells** (Fowler) и **design patterns** (GoF) для агентов при implement / review / debug.
+
+Применять только в scope задачи или MR. Лёгкий refactor — да; «большой» rewrite без явного запроса — нет.
+
+Называть паттерн **только если** репозиторий уже так делает или это минимальный match. Иначе — extract/split/move без ярлыка GoF.
+
+Не заменяет always-on Principles в `code-quality-and-refactoring` (KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition, Demeter).
+
+## When to load
+
+- **Feature delivery / implement** — оценка структуры модулей, границ и дублирования.
+- **Code review** — smells и pattern fit **в диффе MR**, не по всему репо.
+- **Debug** — root-cause похож на wrong abstraction, Feature Envy, Message Chains, Shotgun Surgery.
+- **Light refactor only** — улучшения в рамках boy-scout / MR scope; не расширять задачу ради каталога.
+
+Агенты и skills подгружают stem по one-liner wiring — не копировать этот каталог в промпт агента.
+
+## How to use (agent rules of thumb)
+
+1. Сначала сверить с Principles (always-on): проще ли решение, нет ли ранней абстракции, соблюдён ли public API.
+2. Затем отметить smells **в изменённых файлах** задачи/MR; предложить fix только если он укладывается в light refactor.
+3. Паттерн GoF — опциональный ярлык после того, как структура уже ясна; не начинать дизайн с выбора паттерна.
+4. Если smell и паттерн конфликтуют с границами слоёв стека — побеждают stack boundaries и existing repo patterns.
+5. Не требовать переименования «под GoF», если поведение уже корректно и читаемо.
+
+## Code smells (Fowler, curated ≤12)
+
+Таблица: smell → detect hint → fix hint (одна линия каждый). Без механических меню рефакторинга.
+
+| # | Smell | Detect | Fix hint |
+|---|-------|--------|----------|
+| 1 | Duplicate Code | одинаковая логика в ≥2 местах | dedupe после Rule of Three |
+| 2 | Long Method / Long Module | единица делает слишком много | extract в рамках scope; без big rewrite |
+| 3 | Feature Envy | метод чаще трогает чужие данные, чем свои | сдвинуть логику к данным / public API |
+| 4 | Data Clumps | одни и те же группы аргументов кочуют вместе | сгруппировать в type / value object |
+| 5 | Primitive Obsession | сырые string/int вместо доменных понятий | typed ids / value objects при нужде домена |
+| 6 | Speculative Generality | неиспользуемые хуки, флаги, абстракции «на будущее» | удалить (YAGNI) |
+| 7 | Message Chains | цепочки `a.b.c.d` | Demeter; facade / public API модуля |
+| 8 | Middle Man | класс почти только прокидывает вызовы | убрать pass-through **или** оставить как boundary |
+| 9 | Divergent Change | один модуль меняется по разным причинам | split по поводам изменения |
+| 10 | Shotgun Surgery | одно смысловое изменение разъезжается по многим файлам | consolidate ответственность |
+| 11 | Inappropriate Intimacy | доступ к чужим internals / private деталям | только public API / ports / facades |
+| 12 | Refused Bequest / Parallel Inheritance | подтип игнорирует базу; зеркальные иерархии классов | composition; не плодить параллельные деревья |
+
+**Skip Fowler (не в core):** Lazy Class, Incomplete Library Class, Comments-as-smell dogma, полный каталог 70+, пошаговые recipe-меню.
+
+Приоритет при конфликте smells: Inappropriate Intimacy и Message Chains (границы модулей) > Duplicate Code (после Rule of Three) > Long Method внутри уже правильного модуля.
+
+## Design patterns (GoF, curated ≤8)
+
+Suggest only when repo already uses the shape or the match is minimal. Prefer extract-function over naming Strategy ради ярлыка.
+
+Паттерны ниже — **разрешённый минимум** для агентов; остальной GoF по умолчанию в Skip.
+
+| Pattern | When to suggest | Anti-trigger |
+|---------|-----------------|--------------|
+| Strategy | взаимозаменяемые алгоритмы уже (или явно скоро) выбираются политикой | один алгоритм без ветвления политики |
+| Adapter | обернуть внешний / чужой API под локальный port | лишняя обёртка вокруг своего же API |
+| Facade | упростить multi-step subsystem за public API | facade превращается в god-object |
+| Factory Method | полиморфное создание уже принято в стиле репо | factory на каждый тривиальный `new` |
+| Decorator | аддитивное поведение без взрыва subclass-иерархий | decorator «для слоёв» без реальной нужды |
+| Observer | events / subscriptions уже есть в архитектуре | самодельный pub/sub без прецедента в репо |
+| Template Method | общий algorithm skeleton + вариативные hooks | наследование ради пары отличающихся строк |
+| Composite | дерево однородных узлов (UI/domain), как уже в репо | Composite на плоский список без иерархии |
+
+Если сомневаешься между двумя паттернами — выбери более простой extract/compose без имени; ярлык можно добавить на review, если репо уже так говорит.
+
+## Skip / avoid by default
+
+| Catalog | Skip |
+|---------|------|
+| GoF | Singleton, Abstract Factory, Flyweight, Memento, Interpreter, Visitor, Bridge, Prototype |
+| GoF (conditional) | Command, Chain of Responsibility, State — упоминать **только если** репо уже использует |
+| Fowler | всё сверх 12 smells выше |
+| DDD | Aggregates, bounded-context maps, event sourcing, CQRS — **не в core** |
+| DDD (pointer) | ubiquitous language anti-pattern — расширять в `feature-delivery-workflow`, не здесь |
+| GRASP | список Larman как отдельные правила — skip (перекрывается SOLID/CUPID) |
+| Clean Code dogma | жёсткие caps на строки функции / «ровно один assert» — skip |
+
+Не вводить второй stem (`refactoring-smells` / `design-patterns-for-agents`) — один каталог: `design-guidance`.
+
+## Out of scope for this stem
+
+- Полный GoF (23) и полный Fowler catalog.
+- Stack-specific рецепты (пути модулей, lint-команды) — только в **Stack notes** адаптера.
+- Security, a11y, perf — отдельные review-правила; здесь только структурные smells/patterns.
+- Четвёртое always-on правило — запрещено; этот stem только requestable / agent-load.
+
+## Cross-refs
+
+- Always-on Principles: `code-quality-and-refactoring`.
+- DIP / ports vs adapters: stack `architecture-boundaries` (детали стека — в Stack notes адаптеров).
+- Ubiquitous language: `feature-delivery-workflow` (lineage).
+- MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
+- Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).
+
+## Stack notes
+
+- Strategy via small interfaces at **ports**; adapters (Spring/JPA/HTTP) implement, domain stays free of frameworks.
+- Suggest Facade at package public API; avoid Singleton in favor of composition root / `@Configuration` wiring.
+- Prefer records / immutable VOs for Strategy inputs when the repo already uses them — do not invent patterns mid-module.

package/presets/cursor/java/rules/domain-layer.mdc

@@ -0,0 +1,40 @@
+---
+description: Domain layer invariants for Java hexagonal services
+globs:
+  - domain/**/*
+  - "**/domain/**/*"
+alwaysApply: false
+---
+
+
+# Domain layer
+
+- Pure business types and rules; **no I/O**, no Spring, no JPA, no HTTP.
+- Prefer small value objects with validation factories (`of` / `parse` / package-private constructors) that throw typed **domain** exceptions.
+- Domain errors are typed (`RuntimeException` subtypes or a small sealed hierarchy); map to HTTP/gRPC statuses **only** in adapters.
+- Domain services orchestrate entities/VOs without calling outbound ports (ports live in **application**).
+- Keep invariants close to the type that owns them; avoid anemic bags of fields with all logic in use cases.
+- Prefer `record` / immutable types when the repo already uses them; do not invent a new VO style mid-module.
+
+## Forbidden imports
+
+- Spring (`org.springframework.*`), Jakarta Servlet / JAX-RS resource types, Spring MVC / WebFlux.
+- JPA (`jakarta.persistence.*`, `EntityManager`), Spring Data repositories, JDBC templates as domain deps.
+- Redis/Kafka/HTTP clients, Jackson `@Json*` / OpenAPI annotations that mirror wire contracts.
+- Framework request-scope / security-context plumbing as a substitute for domain deadlines (prefer explicit types).
+
+## Allowed
+
+- JDK: `java.time`, collections, `Optional` sparingly, custom exceptions, pure utilities.
+- Cross-aggregate references by **ID**, not by loading other aggregates via ports.
+- Deadline/time primitives only when the domain API genuinely needs them (prefer application to pass values).
+
+## Plain-Java / alternate frameworks
+
+Same rules: domain stays framework-free whether the edge is Spring Boot, Quarkus, Micronaut, or plain JDK.
+
+## Tests
+
+- JUnit 5 unit tests (parameterized when covering many cases); **no** DB, `MockMvc`, Testcontainers, or Spring contexts.
+- Cover invalid factory inputs and invariant violations explicitly.
+- Prefer AssertJ when the repo already depends on it.

package/presets/cursor/java/rules/feature-delivery-workflow.mdc

@@ -0,0 +1,47 @@
+---
+description: End-to-end delivery checklist for Java hexagonal features
+alwaysApply: false
+---
+
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (Java hexagonal)
+
+Order of work:
+
+1. **Domain** — entities/VOs/errors (`domain-layer`).
+2. **Application + ports** — use case + outbound interfaces (`application-usecases`, `ports-interfaces`).
+3. **Driven adapters** — persistence/cache/messaging implementing ports (`adapters-driven`, `persistence-adapters`).
+4. **Driving adapters** — HTTP/gRPC/CLI mapping DTOs (`adapters-driving`, `api-http`; stubs for gRPC/messaging).
+5. **Composition root** — wire in `configuration/` / `*Application.java` (`composition-root`).
+6. **Tests** — unit (domain/app) → integration (adapters) → optional e2e smoke.
+7. **Gate** — `post-change-test` (+ `java-tooling`).
+
+```mermaid
+flowchart LR
+  D[Domain] --> A[Application+Ports]
+  A --> Drv[Driven adapters]
+  Drv --> A
+  HTTP[Driving HTTP] --> A
+  CR[Composition root] --> HTTP
+  CR --> A
+  CR --> Drv
+```
+
+## Matrix
+
+| Path | Rules |
+|------|-------|
+| `**/domain/**` | `domain-layer`, `architecture-boundaries` |
+| `**/application/**` | `application-usecases`, `ports-interfaces` |
+| `**/adapters/inbound/**`, `**/adapters/http/**` | `adapters-driving`, `api-http` / `api-grpc` |
+| `**/adapters/outbound/**`, `**/adapters/persistence/**` | `adapters-driven`, `persistence-adapters` / `messaging-adapters` |
+| `**/configuration/**`, `**/*Application.java` | `composition-root` |
+| After `*.java` edits | `post-change-test` (+ `java-tooling`) |
+
+## Anti-patterns
+
+- Framework types in domain; SQL/JPQL in use cases; DI inside controllers; skipping port interfaces “for speed”; returning JPA entities as HTTP bodies.
+- **Ubiquitous language:** Domain names/boundaries reflect the feature domain — do not mix transport/framework terms into domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- Spring Boot is the default edge; plain Java / Quarkus / Micronaut keep the same layer order with different wiring.

package/presets/cursor/java/rules/java-app-core.mdc

@@ -0,0 +1,33 @@
+---
+description: Java/Spring Boot hexagonal stack, module layout, and agent entry points
+alwaysApply: true
+---
+
+
+# Стек и окружение
+
+Версии JDK, Spring Boot и зависимостей — **из `pom.xml` / `build.gradle(.kts)` целевого репозитория**. Рамка preset:
+
+- **Язык / платформа:** Java (Maven или Gradle; wrappers `./mvnw` / `./gradlew` предпочтительны).
+- **Default:** Spring Boot **hexagonal** (ports & adapters); domain не знает Spring/JPA/HTTP.
+- **Variants (documented):** plain Java, Quarkus, Micronaut, Jakarta EE — те же границы пакетов.
+- **Layout default:** layer-first single-module; multi-module — documented variant.
+- **Тесты:** JUnit 5 + AssertJ; integration — Testcontainers; REST Assured — optional smoke.
+- **HTTP:** Spring MVC / Jakarta at the edge (примеры, не жёсткий мандат framework).
+- **Static analysis:** discover from repo/CI — do not mandate Checkstyle/SpotBugs/Error Prone.
+
+# Структура (default: layer-first)
+
+```text
+src/main/java/<base>/
+  domain/
+  application/                 # use cases + ports
+  adapters/inbound/http/
+  adapters/outbound/persistence|messaging|external/
+  configuration/               # Spring @Configuration / plain composition
+src/test/java/<base>/
+```
+
+**Feature-first variant:** `<feature>/{domain,application,adapters}` — same dependency direction.
+
+Границы — **`architecture-boundaries.mdc`**. Tooling — requestable **`java-tooling.mdc`**. После правок Java — **`post-change-test.mdc`**.

package/presets/cursor/java/rules/java-conventions.mdc

@@ -0,0 +1,54 @@
+---
+description: Idiomatic Java conventions for this hexagonal preset
+globs:
+  - "**/*.java"
+alwaysApply: false
+---
+
+
+# Java conventions
+
+- Follow Effective Java and the repository's formatter / static-analysis config when present.
+- Prefer `record` / immutable value types for DTOs and domain VOs when the repo already uses them.
+- Naming: `PascalCase` types, `camelCase` methods/fields, lowercase package segments; match neighboring packages.
+- Prefer package-private by default; expose only what other modules need via public types.
+- Prefer parameterized JUnit 5 tests (`@ParameterizedTest`) when covering multiple cases.
+- Do not invent library APIs — verify symbols against `pom.xml` / `build.gradle(.kts)` and existing imports (`// VERIFY:` when unsure).
+
+## Errors / exceptions
+
+- Prefer unchecked exceptions (`RuntimeException` subtypes) for domain/application failures unless the repo's public API requires checked exceptions.
+- Chain causes (`new X(msg, cause)`); never empty-catch without logging or rethrowing.
+- Prefer domain-specific exception types for structured cases; avoid broad `catch (Exception)`.
+- Map to HTTP/gRPC statuses only in adapters — do not throw `ResponseStatusException` from domain.
+
+## Interfaces / ports
+
+- Depend on interfaces (ports) at the call site; return concrete types from factories when simple.
+- Keep interfaces small (ISP); define ports in application, not on every adapter class «just in case».
+
+## Packages
+
+- Avoid `util`/`common` dumping grounds — name by domain capability.
+- Keep `@SpringBootApplication` / configuration / `main` thin (see `composition-root`).
+- No static mutable request state; no business logic in static initializers.
+
+## Concurrency
+
+- Prefer executor / structured patterns already used in the repo; document cancellation (interrupt, reactive cancel, request-scoped cancel).
+- Do not start unbounded threads/executors from handlers without a shutdown/supervision story.
+- Match existing package patterns for locks / concurrent collections — do not invent frameworks.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Empty `catch` / ignored failures | Handle, wrap with cause, or declare |
+| Interfaces on every class «just in case» | Ports at consumer / call site |
+| Invented modules not in `pom.xml` / `build.gradle` | Add dependency explicitly or copy existing import |
+| Raw `Object` / untyped `Map` where a typed type fits | Generics / records / domain types used by the repo |
+| Business logic in static initializers | Wire in composition root / Spring config |
+
+## Agent requirement
+
+New Java code must stay idiomatic and verifiable against `pom.xml` / `build.gradle` and neighboring packages. Less guessed code is better than more.

package/presets/cursor/java/rules/java-tooling.mdc

@@ -0,0 +1,34 @@
+---
+description: Java toolchain commands (Maven/Gradle test, verify) — requestable
+globs:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+alwaysApply: false
+---
+
+# Java tooling (requestable)
+
+Before running commands, detect the build tool from the repository:
+
+1. Prefer wrappers when present: `./mvnw`, `./gradlew`.
+2. `pom.xml` → Maven; `build.gradle` / `build.gradle.kts` → Gradle.
+3. If both descriptors exist, follow CI/README — do not guess.
+4. JDK version — from toolchain plugin, `maven.compiler.release` / Gradle toolchain, or CI image.
+
+## Typical commands
+
+| Goal | Maven | Gradle |
+|------|-------|--------|
+| Unit/integration tests | `./mvnw test` or `mvn test` | `./gradlew test` |
+| Packaged verify (if configured) | `./mvnw verify` | `./gradlew check` |
+| Compile only | `./mvnw -DskipTests compile` | `./gradlew classes` |
+
+Static analysis / formatters (Checkstyle, SpotBugs, Error Prone, Spotless, etc.) — **run only if the repo/CI already configures them**. Do not introduce a new tool as a hard gate.
+
+## Agent requirements
+
+- Mandatory after Java edits: **`post-change-test.mdc`**.
+- Never require Playwright, XCUITest, `lint:js`, `lint:css`, or `xcodebuild` as Java handoffs.
+- Integration tests: prefer Testcontainers / Spring test slices — agents `integration-test-*`.

package/presets/cursor/java/rules/messaging-adapters.mdc

@@ -0,0 +1,26 @@
+---
+description: Messaging driven/driving adapters for Java hexagonal services (stub)
+globs:
+  - "**/adapters/outbound/messaging/**/*"
+  - "**/adapters/inbound/messaging/**/*"
+  - "**/adapters/messaging/**/*"
+alwaysApply: false
+---
+
+
+# Messaging adapters (documented stub)
+
+> **Stub (v1):** Light guidance only — not a full Kafka/Rabbit/JMS cookbook. **When to use:** editing `adapters/**/messaging/**` or adding broker publishers/consumers. Prefer expanding this rule when the consumer repo standardizes on a broker.
+
+- **Publisher** (driven): implements outbound port; serializes domain events / integration events.
+- **Consumer** (driving): deserializes → calls use case / inbound port; ack/nack policy here.
+- Idempotency keys and retry/DLQ are adapter concerns; document at-least-once assumptions.
+- Do not put broker client types (`KafkaTemplate`, JMS sessions, etc.) in domain or application signatures.
+
+## Event shapes
+
+- Prefer explicit event types in application or a small `events` package used by ports — map to wire format in the adapter.
+
+## Tests
+
+- Unit-test mapping with fakes; integration against embedded/broker Testcontainers when the repo has them.

package/presets/cursor/java/rules/module-public-api.mdc

@@ -0,0 +1,33 @@
+---
+description: Public module API and package boundaries for Java services
+globs:
+  - "**/api/**/*.java"
+  - "**/module-info.java"
+  - pom.xml
+  - "**/build.gradle*"
+alwaysApply: false
+---
+
+
+# Module public API
+
+- Published types under a module's public packages are a compatibility surface — change carefully; prefer additive APIs.
+- Service-private code stays in implementation packages — do not treat every package as public API.
+- Prefer package-private by default; expose only what other modules/features need.
+- Do not deep-import another module's internal packages; depend on its published API / facade only.
+- Document breaking Java API changes in CHANGELOG when the repo publishes libraries.
+
+## Single-module default / multi-module variant
+
+- **Default:** one deployable module with layer-first packages under `src/main/java/<base>/`.
+- **Multi-module (Maven/Gradle):** each module exposes a narrow public API; application ports may live in an `application-api` module; adapters depend inward. Do not invent multi-module scaffolding unless the repo already uses it.
+
+## pom.xml / build.gradle
+
+- Module coordinates and JDK version are SoT for toolchain.
+- Prefer minimal direct deps; pin via BOM / lockfile the repo already uses (`pom.xml`, `build.gradle(.kts)`).
+
+## Cross-feature
+
+- Inside one module, features communicate via application ports or small public facades — not by importing sibling feature adapter packages.
+- JPMS `module-info.java` (when present): export only public packages; keep adapters non-exported when possible.

package/presets/cursor/java/rules/persistence-adapters.mdc

@@ -0,0 +1,35 @@
+---
+description: Persistence driven adapters (JPA/JDBC/repos) for Java hexagonal services
+globs:
+  - "**/adapters/outbound/persistence/**/*"
+  - "**/adapters/persistence/**/*"
+  - "**/*Repository*.java"
+  - "**/*repository*.java"
+alwaysApply: false
+---
+
+
+# Persistence adapters
+
+- Implement outbound repository ports from application.
+- Use parameterized queries / JPA Criteria / Spring Data methods — **never** string-concatenated SQL with untrusted input.
+- Map rows / JPA entities → **domain** inside the adapter; entities stay private to the adapter package when possible.
+- Transactions: use cases own the boundary (`@Transactional` on application services, or a `UnitOfWork` port). Adapters must not start ad-hoc transactions that hide business atomicity.
+- Migrations live with infra (`db/migration`, Flyway/Liquibase dirs) — **not** in domain.
+
+## Mapping
+
+- JPA `@Entity` / JDBC row mappers are adapter-local; do not pass them through port signatures or up into application/domain.
+- Nullability and DB defaults convert to domain values explicitly (no silent nulls into invariants).
+- Spring Data repositories may be used **inside** the adapter as helpers; the application still depends on the port interface, not on `JpaRepository`.
+
+## Forbidden
+
+- Importing persistence from domain, or leaking `EntityManager` / `@Entity` / `JdbcTemplate` through port APIs.
+- Building SQL/JPQL strings in use cases.
+- Returning JPA entities from REST controllers “because lazy loading”.
+
+## Tests
+
+- Integration tests with Testcontainers / test DB preferred for repos; unit-test mappers with fixtures.
+- Spring `@DataJpaTest` / JDBC slices only when needed — prefer testing through the port implementation.

package/presets/cursor/java/rules/ports-interfaces.mdc

@@ -0,0 +1,36 @@
+---
+description: Inbound and outbound port interfaces for Java hexagonal services
+globs:
+  - "**/ports/**/*"
+  - application/**/*port*
+  - "**/application/**/*port*"
+alwaysApply: false
+---
+
+
+# Ports (interfaces)
+
+## Outbound (driven)
+
+- Repository, cache, publisher, clock, ID generator, external client — defined by **application** (owner of the need).
+- Signatures use **domain** types (or small application DTOs), never JPA `@Entity`, JDBC `ResultSet`, or broker message types.
+- Keep interfaces small (ISP); prefer role interfaces over god-repos (`OrderRepository` vs `EverythingRepository`).
+- Do not put Spring Data / JPA repository interfaces in domain; if Spring Data is used, it stays in the outbound adapter and implements (or is wrapped by) the application port.
+
+## Inbound (driving)
+
+- Optional interface wrapping use cases for multiple drivers (HTTP + gRPC + CLI + messaging consumer).
+- Drivers depend on inbound ports / use-case APIs — not on each other.
+- Prefer a concrete use-case class when only one driver exists; extract an interface when a second driver appears (Rule of Three / YAGNI).
+
+## Naming
+
+- `saveOrder`, `findOrderById`, `publishOrderPlaced` — verb-oriented; match neighboring package style.
+- Implementation types live in adapters (`JpaOrderRepository`, `JdbcOrderRepository`), not beside the interface in domain.
+
+## Anti-patterns
+
+- Ports returning untyped `Map<String, Object>`, raw `JsonNode`, or framework entities.
+- Putting port interfaces inside adapter packages (wrong owner — adapters implement, application defines).
+- Leakage of `EntityManager`, `@Entity`, `JdbcTemplate`, or Redis types through port method signatures.
+- One mega-port “for convenience” that every use case depends on.

package/presets/cursor/java/rules/post-change-test.mdc

@@ -0,0 +1,30 @@
+---
+description: Mandatory verification after Java code edits (Maven/Gradle test + repo static gates)
+globs:
+  - "**/*.java"
+  - "**/pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+alwaysApply: false
+---
+
+# Post-change test (requestable, mandatory after Java edits)
+
+After changing Java sources or build descriptors:
+
+1. Detect Maven vs Gradle via **`java-tooling.mdc`** (wrappers preferred).
+2. Run the repository test task (`mvn test` / `./gradlew test`, or the CI-documented equivalent).
+3. If the repo defines a verify/check profile (Failsafe, `check`, Spotless, etc.), run that next.
+4. Apply **only** formatter/static-analysis steps already wired in the project or CI — do not mandate Checkstyle, SpotBugs, or Error Prone.
+
+## Pass / fail
+
+- **PASS:** tests green; configured static gates green (when present).
+- **FAIL:** red tests or configured gate failures — fix before handoff.
+- Do **not** substitute yarn `lint:js`/`lint:css`, Playwright, XCUITest, or `xcodebuild`.
+
+## Related
+
+- Tooling discovery: `java-tooling.mdc`
+- Unit: `tests-unit.mdc` (JUnit 5)
+- Integration: `tests-integration.mdc` + `integration-test-*` agents

package/presets/cursor/java/rules/preset-layering.mdc

@@ -0,0 +1,36 @@
+---
+description: Preset authoring meta-rule (preset-layering)
+globs:
+  - packages/ai-rules/presets/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+alwaysApply: false
+---
+
+<!-- shared-core: meta/preset-layering.md -->
+
+# Preset layering
+
+Правила для **авторов пресетов** (`packages/ai-rules/presets/**`). Не always-on в consumer apps.
+
+## Слои
+
+| Слой | Где | Что класть |
+|------|-----|------------|
+| **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; без frontmatter; без путей `app/**`, `Features/**`, Playwright, xcodebuild |
+| **Stack** | `presets/{cursor\|claude}/<stack>/` | Domain/tooling, always-on trio стека, stack examples в **Stack notes** |
+| **Platform** | Cursor `.mdc` / Claude `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
+
+## Куда класть новое правило
+
+1. Общие принципы для всех стеков → **core** + адаптеры с `<!-- shared-core: … -->`.
+2. Только один из installable стеков (`next` / `ios-swift` / `go` / `java`) → **stack-specific** (не в `_shared`).
+3. Только Cursor или только Claude packaging → platform artifact / frontmatter, не дублировать семантику.
+
+## SoT
+
+- Packages path — SoT; root `.cursor/` — dogfood sync.
+- Per stack: **Cursor** `presets/cursor/<stack>/` → Claude twin same PR.
+- `_shared` **не** `--preset` и не копируется CLI `init`.
+
+См. также: `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`.

package/presets/cursor/java/rules/preset-no-cross-stack-leakage.mdc

@@ -0,0 +1,56 @@
+---
+description: Preset authoring meta-rule (preset-no-cross-stack-leakage)
+globs:
+  - packages/ai-rules/presets/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+alwaysApply: false
+---
+
+<!-- shared-core: meta/preset-no-cross-stack-leakage.md -->
+
+# Preset no cross-stack leakage
+
+Запрет протекания stack-specific имён, путей и handoff stems между пресетами.
+
+## Principles
+
+- `next` must not require iOS-only agents/tooling (`xcuitest-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `ios-swift` must not ship Playwright handoffs or Next lint recipes as required commands.
+- `go` / `java` must not ship Playwright, XCUITest, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+
+## Forbidden in ios-swift hooks/agents (FAIL)
+
+In ios-swift `chain-team-phases.sh` / agent handoffs (Cursor + Claude):
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`
+- `app/__tests__/e2e` as a required path
+- Positive yarn recipes `lint:js` / `lint:css` as commands to run (negation prose alone is weak — prefer zero occurrences)
+
+Required instead: `xcuitest-test-*` stems; build-verifier mentions `xcodebuild` or `post-change-build` / `xcode-tooling`.
+
+## Forbidden in next hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for Next app work
+
+## Forbidden in go / java hooks/agents (FAIL)
+
+Shared backend-stack bans (both `go` and `java`):
+
+- `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
+- Positive yarn recipes `lint:js` / `lint:css`
+- `xcuitest-test-`, `xcodebuild`, `SwiftLint` as required handoffs
+- Agent file `accessibility-reviewer` (no UI surface)
+
+Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`) or `java-tooling` (`mvn test` / `./gradlew test`).
+
+## Soft / document
+
+- Mentioning the other stack in **docs** comparing presets is OK.
+- `build-verifier` may reference other stacks when validating **preset packaging** (`scope: preset-structure-validation`).
+
+## Chain fork
+
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `ios-swift`, `go`, and `java` (per platform).

package/presets/cursor/java/rules/preset-pr-checklist.mdc

@@ -0,0 +1,39 @@
+---
+description: Preset authoring meta-rule (preset-pr-checklist)
+globs:
+  - packages/ai-rules/presets/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+alwaysApply: false
+---
+
+<!-- shared-core: meta/preset-pr-checklist.md -->
+
+# Preset PR checklist
+
+Чеклист для PR, затрагивающих `packages/ai-rules/presets/**` (и dogfood `.cursor/` sync).
+
+## Before merge
+
+- [ ] **SoT:** правки в `packages/…` (не только root `.cursor/`)
+- [ ] **Core:** если менялся `_shared/core/**` — обновлены все `<!-- shared-core: … -->` consumers (или documented intentional fork)
+- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, ios-swift, go, and java — см. `preset-twin-sync`)
+- [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table актуален
+- [ ] **Token budget:** alwaysApply / session-start ≤ 3; meta rules not always-on
+- [ ] **Leakage:** нет чужих stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
+- [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
+- [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
+- [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (or document intentional skip) when maintaining this monorepo
+- [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
+
+## Pointers
+
+- Layering: `preset-layering`
+- Sync: `preset-twin-sync`
+- Budget: `preset-token-budget`
+- Leakage: `preset-no-cross-stack-leakage`
+- Validation: stack `agents/build-verifier.md` → preset-structure section
+- Dogfood script: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`
+- Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
+- Orchestrator: when editing presets, load this checklist + twin-sync