@bonesofspring/ai-rules 0.2.5 → 0.2.6

package/presets/claude/ios-swift/rules/tooling-and-review/code-quality.md

@@ -2,37 +2,70 @@
 description: Поддержка и улучшение качества кода и архитектуры iOS
 ---
 
+<!-- shared-core: quality/code-quality-and-refactoring.md -->
+
 # Поддержка существующего стиля
 
 - Новые изменения должны:
-  - следовать существующим паттернам (имена, структура, DI, error handling);
-  - минимизировать «стилистический шум» (лишний reformat, rename без нужды).
-- Перед новым решением:
-  - искать аналог в коде и **повторять подход**;
-  - проверять DesignSystem и существующие компоненты перед новым UI-контролом;
-  - обращаться к другим фичам только через public API (протоколы, facades).
+  - следовать существующим паттернам (имена, структура, типизация / DI / error handling стека);
+  - минимизировать «стилистический шум» (лишние правки форматирования, rename без нужды).
+- Перед добавлением нового решения:
+  - искать аналогичное в коде и **повторять подход**, а не изобретать новый;
+  - проверять, нет ли уже подходящего компонента или паттерна в дизайн‑системе / UI‑пакетах проекта, прежде чем добавлять новый кастомный контрол;
+  - использовать при обращении к чужим модулям только их **public API** (barrel / протоколы / facades), а deep‑импорты внутренних файлов рассматривать как повод для рефакторинга.
+
+# Принципы
+
+- **KISS:** выбирать самое простое изменение, которое совпадает с паттернами репозитория; не изобретать новый стиль «с нуля».
+- **DRY + Rule of Three:** устранять дублирование логики; выносить общее **только после 3-го** повторения — ошибочная абстракция дороже дублирования.
+- **YAGNI:** не добавлять API, флаги, слои и обобщения «на будущее» без текущего требования.
+- **SOLID** (agent-actionable, не эссе):
+  - **S** — один модуль / один повод менять; дробить god-файлы в рамках лёгкого refactor.
+  - **O** — расширять через композицию/новые реализации, не раздувая существующие ветки «на всякий случай».
+  - **L** — подтип не ломает контракт базового типа/протокола.
+  - **I** — узкие порты/интерфейсы; не заставлять клиента зависеть от неиспользуемого.
+  - **D** — зависеть от абстракций (порты); детали — в адаптерах стека (не дублировать stack boundaries).
+- **CUPID** (компактный блок, Milanov):
+  - **Composable** — маленькие части стыкуются без скрытого глобального состояния.
+  - **Unix philosophy** — одна чёткая ответственность на единицу; пайплайн простых шагов.
+  - **Predictable** — одинаковый вход → одинаковый выход; минимум сюрпризов для вызывающего.
+  - **Idiomatic** — следовать идиомам языка и **существующим** конвенциям репо.
+  - **Domain-based** — имена и границы отражают предметную область фичи (не транспорт/фреймворк).
+- **Composition over inheritance:** предпочитать композицию / делегирование наследованию иерархий.
+- **Law of Demeter (hint):** не строить цепочки `a.b.c.d`; ходить через public API / facade модуля.
 
 # Рефакторинг при изменениях
 
-- Допустим лёгкий refactor, если он:
+- Разрешён лёгкий refactor, если он:
   - уменьшает дублирование;
   - повышает читаемость;
-  - не ломает публичные контракты.
-- Примеры:
-  - вынести дублирующийся mapper или validation;
-  - заменить force unwrap на безопасные конструкции;
-  - разбить перегруженный ViewModel на use cases;
-  - заменить magic numbers/colors на design tokens;
-  - убрать прямую зависимость View от Data в пользу протокола.
+  - не ломает публичные контракты модулей.
+- Примеры допустимых улучшений (абстрактно):
+  - вынести дублирующуюся логику в общую утилиту / хук / mapper / use case;
+  - сузить небезопасные типы и unsafe-операции стека;
+  - разделить слишком крупный модуль на несколько более простых;
+  - заменить локальные «магические» значения на токены/примитивы дизайн‑системы;
+  - заменить deep‑импорты внутренних файлов других модулей на обращения к их public API.
 
 # Ограничения
 
-- Не делать «большой» рефакторинг при точечной задаче:
-  - не менять структуру модулей/таргетов;
-  - не переименовывать public API без запроса.
-- Крупные изменения — минимальными шагами, код остаётся компилируемым.
+- Не выполнять «большой» рефакторинг, если задача точечная и не про архитектуру:
+  - не менять структуру директорий / модулей / таргетов без нужды;
+  - не менять названия публичных типов/функций/API без явного запроса.
+- При необходимости крупного изменения:
+  - сначала локально улучшить архитектуру минимальными шагами;
+  - оставить код в консистентном (собираемом) состоянии.
 
 # Требование к агенту
 
-- **Boy scout rule:** оставлять модуль чуть лучше (безопасность optional, typed errors, tests).
-- Не жертвовать слоями ради краткости.
+- **Boy scout rule:** оставлять модуль немного лучше, чем до изменения (простые, безопасные улучшения).
+- Не жертвовать архитектурой и слоями ради краткости реализации.
+
+> Stack-specific lint gates, примеры и toolchain — в секции **Stack notes** адаптера пресета.
+
+## Stack notes
+
+- Перед новым UI‑контролом проверять DesignSystem и существующие компоненты.
+- Public API: протоколы и facades между фичами.
+- Примеры: mapper/validation; force unwrap → safe; разбить ViewModel; design tokens; View не зависит от Data напрямую.
+- Post-change: **`tooling-and-review/post-change-build.md`** + `tooling-and-review/xcode-tooling.md`.

package/presets/claude/ios-swift/rules/tooling-and-review/code-review.md

@@ -7,40 +7,34 @@ paths:
   - .claude/skills/code-review/**/*
 ---
 
+<!-- shared-core: review/code-review-mr.md -->
+
 # Code review merge requests
 
-On-demand правило для review-потоков (не always-on).
-
-- **Когда применять**
-  - Запросы: «проведи ревью», «оцени MR/ветку/дифф», «посмотри изменения».
-  - Опираться на локальный репозиторий: ветка, `git diff`, открытые файлы.
-
-- **Что обязан проверить агент**
-  - **Архитектура и слои** (`architecture/boundaries.md`, `stack/ios-app-core.md`):
-    - View не вызывает API и не знает DTO.
-    - ViewModel не зависит от Data-реализаций напрямую.
-    - Domain не импортирует SwiftUI/UIKit.
-    - Data не тянет Presentation.
-  - **Зависимости и модули**:
-    - DI через протоколы; composition root в App.
-    - Нет deep-import между фичами.
-    - Файлы в правильных слоях (`Presentation`, `Domain`, `Data`, `DesignSystem`).
-  - **Swift и concurrency** (`stack/swift-conventions.md`):
-    - `@MainActor` на UI; нет необоснованных force unwrap.
-    - Typed errors; корректная отмена Task где нужно.
-  - **UI** (`ui-and-accessibility/swiftui.md`):
-    - Тонкие Views; Design System tokens; accessibility identifiers для тестируемых элементов.
-  - **Сеть и data** (`api-and-data/networking.md`):
-    - DTO отделены от domain; mappers покрывают edge cases.
-  - **Тесты**:
-    - Нетривиальная логика — unit (`testing/unit.md`); пользовательские потоки — UI (`testing/ui.md`).
-    - Указать, какие тесты добавить или обновить.
-
-- **Глубина и формат**
-  - Фокус на **диффе MR**, не на всём проекте.
-  - Сначала обзор (цель MR, риски), затем конкретные комментарии с файлом и предложением fix по паттернам репо.
-  - Без «больших рефакторингов» без запроса (`tooling-and-review/code-quality.md`).
-
-- **Ограничения**
-  - Не выдумывать метаданные CI/MR с хостинга без локальных данных.
-  - Boy scout rule в рамках MR.
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+## When to load
+
+- User asks for review/MR/diff
+- Pipeline step `code-reviewer`
+- Platform automated review (e.g. BUGBOT) when present
+
+## Checklist references (abstract)
+
+- Architecture layers and stack core rules
+- Public imports / module boundaries
+- UI conventions of the stack
+- Unit and e2e/UI test conventions
+- Post-change lint/build gate before final report
+- Design smells **in MR diff scope** — load `design-guidance`; не разворачивать полный каталог Fowler вне диффа
+- Pattern name (GoF) — только если репозиторий уже использует эту форму или match минимален
+- Principles (KISS / DRY+Ro3 / YAGNI / SOLID / CUPID) — через always-on `code-quality-and-refactoring`, не дублировать эссе в review
+
+Concrete rule stems — in **Stack notes**.
+
+## Constraints
+
+- Focus on MR diff, not the whole repo.
+- Use local `git diff` — do not invent hosting metadata.
+- Boy scout rule: suggest fixes feasible within the MR scope.
+- No «большие рефакторинги» without an explicit request (`code-quality-and-refactoring`).

package/presets/claude/ios-swift/rules/tooling-and-review/design-guidance.md

@@ -0,0 +1,110 @@
+---
+description: Design smells (Fowler) and curated GoF patterns for agents. Load when assessing structure, smells, or pattern fit.
+paths:
+  - "**/*.swift"
+---
+
+<!-- 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
+
+- Prefer protocol + composition over class inheritance hierarchies.
+- Suggest Adapter/Facade at Feature public API / DI boundaries — not inside Views.

package/presets/claude/ios-swift/rules/tooling-and-review/preset-layering.md

@@ -0,0 +1,36 @@
+---
+description: Preset authoring: Core → Stack → Platform layering. Use when editing packages/ai-rules/presets/**.
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- 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`) → **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/claude/ios-swift/rules/tooling-and-review/preset-no-cross-stack-leakage.md

@@ -0,0 +1,54 @@
+---
+description: Preset authoring: forbid cross-stack agent/path leakage in hooks and agents.
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- 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` 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 hooks/agents (FAIL)
+
+- `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` / `go-tooling` (`go test`, `go vet`).
+
+## 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`, and `go` (per platform).

package/presets/claude/ios-swift/rules/tooling-and-review/preset-pr-checklist.md

@@ -0,0 +1,39 @@
+---
+description: Preset authoring: PR checklist for twin sync, budget, leakage, README. Use on preset PRs.
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- 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, and go — см. `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

package/presets/claude/ios-swift/rules/tooling-and-review/preset-token-budget.md

@@ -0,0 +1,41 @@
+---
+description: Preset authoring: ≤3 always-on / session-start; meta rules never alwaysApply.
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- shared-core: meta/preset-token-budget.md -->
+
+# Preset token budget
+
+Инварианты загрузки правил в **установленном** пресете (consumer app).
+
+## Hard caps
+
+| Platform | Always-on | Cap |
+|----------|-----------|-----|
+| Cursor | `alwaysApply: true` | **≤ 3** |
+| Claude | rules **without** `paths:` | **ровно 3** |
+
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+
+Session-start body budget (где задокументировано): ≤120 строк суммарно (stretch ≤100).
+
+## Meta / author rules
+
+Rules for preset authors (`preset-layering`, `preset-twin-sync`, …):
+
+- **Never** `alwaysApply: true` on consumer installs.
+- Cursor: `globs` limited to `packages/ai-rules/presets/**` (and dogfood `.cursor/**` where useful).
+- Claude: `paths:` limited to `packages/ai-rules/presets/**` (and `.claude/**` dogfood if present).
+
+## Heavy workflows
+
+Orchestrator, feature-delivery, code-review, post-change gates, domain globs — **requestable / paths**, not always-on.
+
+## Verifier
+
+build-verifier **FAIL** if alwaysApply / session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/claude/ios-swift/rules/tooling-and-review/preset-twin-sync.md

@@ -0,0 +1,42 @@
+---
+description: Preset authoring: Cursor SoT → Claude twin same PR. Use when editing preset rules.
+paths:
+  - packages/ai-rules/presets/**/*
+  - .claude/**/*
+  - .cursor/rules/**/*
+  - .cursor/team/tasks/**/*
+---
+
+<!-- shared-core: meta/preset-twin-sync.md -->
+
+# Preset twin sync
+
+Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
+
+## Matrix
+
+| Stack | Cursor SoT | Claude derive | Mapping table |
+|-------|------------|---------------|---------------|
+| `next` | `presets/cursor/next/rules/*.mdc` | `presets/claude/next/rules/<topic>/` | **Required** in `claude/next/rules/README.md` |
+| `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Keep in `claude/ios-swift/rules/README.md` |
+| `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
+
+## Same-PR checklist
+
+1. Edit Cursor rule first (body + frontmatter).
+2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
+3. Update mapping table row if stem/path changed.
+4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
+
+## Twin depth
+
+- **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
+- **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
+
+## Severity (build-verifier)
+
+- **next:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **ios-swift:** missing Claude twin for a changed Cursor rule → **FAIL**.
+- **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
+
+Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.

package/presets/claude/ios-swift/rules/tooling-and-review/technical-retro.md

@@ -5,10 +5,12 @@ paths:
   - .claude/team/**/*
 ---
 
+<!-- shared-core: review/technical-retro.md -->
+
 # Техническое ретро — rule alias
 
-Полный сценарий — в slash-команде:
+Полный сценарий (включая блок **«Работа агентов»** для slug из team tasks) — в slash-команде:
 
-**`.claude/commands/technical-retro.md`** → `/technical-retro`
+**`commands/technical-retro.md`** → `/technical-retro`
 
-Используй rule только если command недоступен. Не дублируй содержимое — следуй command-файлу и skill `technical-retro`.
+Используй rule только если command недоступен. Не дублируй содержимое command в ответе — следуй command-файлу и skill `technical-retro`.

package/presets/claude/ios-swift/skills/code-review/SKILL.md

@@ -25,3 +25,7 @@ Use the local repository as the source of truth: `git status`, `git diff`, task
 Lead with findings ordered by severity. Each finding should include the file, the problem, impact, and a concrete fix direction. If there are no findings, say so and call out remaining test or validation risk.
 
 For agent team tasks, write `.claude/team/tasks/<slug>/review.md` and set `status.json` to `completed` or `changes_requested`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/ios-swift/skills/debug-investigation/SKILL.md

@@ -28,3 +28,7 @@ For agent team tasks, write `.claude/team/tasks/<slug>/debug-report.md` with:
 Update `status.json` when complete.
 
 Do not use browser/Playwright tooling — this is an Xcode stack.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/ios-swift/skills/feature-delivery/SKILL.md

@@ -25,3 +25,7 @@ When editing **ai-rules ios-swift preset** sources (agents, hooks, rules) rather
 ## Handoff
 
 Summarize by layer, validation results, and known gaps. Agent team: update `.claude/team/tasks/<slug>/status.json`.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/README.md

@@ -16,11 +16,19 @@
 
 Файлы правил — обычный Markdown с опциональным YAML frontmatter (`paths:` для скоупа по путям), не формат `.mdc` Cursor.
 
+## Preset taxonomy & contributing
+
+- **Layers:** Core → Stack → Platform — [`../../_shared/README.md`](../../_shared/README.md)
+- **Contribution guide:** [`../../docs/PRESET-CONTRIBUTION.md`](../../docs/PRESET-CONTRIBUTION.md)
+- **Cursor SoT:** `presets/cursor/next/` — этот пресет derived twin; правки Cursor first, same PR
+- **Cursor→Claude map + core table:** [`rules/README.md`](./rules/README.md)
+- **Author meta:** `tooling-and-review/preset-*.md` (`paths:` on `packages/ai-rules/presets/**` only)
+
 ## Agent team workflow
 
 Cursor-пресет и Claude-пресет используют один и тот же смысловой workflow:
 
 - `/task <desc>` → `task-router` → `pipeline.json`;
 - `/task-continue <slug>` → продолжение после human gate;
-- `.claude/agents/*.md` → 20 ролей: planning (router, analyst, architect, migration, api-contract), implementation (debugger, ci-investigator, developer), review (code, a11y, security, perf), testing (QA, unit trio, playwright trio), docs (tech-writer);
+- `.claude/agents/*.md` → **21** ролей: planning (router, analyst, architect, migration, api-contract), implementation (debugger, ci-investigator, developer), review (code, a11y, security, perf), testing (QA, unit trio, playwright trio), docs (tech-writer), build (build-verifier);
 - `.claude/team/tasks/<slug>/` → handoff-артефакты (`brief.md`, `decomposition.md`, `review.md`, `migration-plan.md`, `ci-report.md`, `status.json`, …).

package/presets/claude/next/agents/build-verifier.md

@@ -25,6 +25,30 @@ Use **`rules/tooling-and-review/package-manager.md`** for the repo package manag
 
 Prefer **`lint`** (= js + css + type-check) before handoff on large changes.
 
+## Preset-structure validation (when scope is preset / packages/ai-rules)
+
+When validating **preset packaging** changes (paths under `packages/ai-rules/presets/**`, or `scope: preset-structure-validation` / `preset-artifacts-only`), run these checks. Skip app lint if there are **no** app source changes.
+
+### FAIL (all stacks)
+
+1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be session-start (must have `paths:`).
+2. **Leakage (next):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default Next post-change gate. See `tooling-and-review/preset-no-cross-stack-leakage.md`.
+3. **Mapping / README:** `rules/README.md` must include a Cursor→Claude mapping table; document core→stack mapping when `_shared` consumers exist.
+4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented).
+5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, ios-swift, and go). Domain twin body ≥15 lines; thin aliases may be shorter.
+6. **Session-start body budget:** sum body lines of the **3** intended session-start rules ≤ **120** (stretch ≤100); do **not** include `**/README.md` — record in validation-report; FAIL if grossly over.
+7. **Embed drift (soft by default):** run `packages/ai-rules/scripts/check-shared-core-drift.sh`. Document DRIFT; `AI_RULES_DRIFT_FAIL=1` to enforce. Lineage stems excluded from body equality.
+8. **Dogfood (monorepo soft):** prefer `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass dogfood deletion without migration doc → risk / FAIL for maintainers.
+
+### Soft notes
+
+- Thin aliases may be &lt;15 body lines.
+- Embed vs lineage: `docs/PRESET-CONTRIBUTION.md`, `_shared/README.md`.
+
+### ios-swift-only checks
+
+When ios-swift paths are also in the PR, apply ios-swift verifier checks (chain fork, Playwright leakage) — **FAIL**.
+
 ## Output
 
 Write `.claude/team/tasks/<slug>/validation-report.md`:

package/presets/claude/next/agents/code-reviewer.md

@@ -61,3 +61,7 @@ Update `status.json`:
 If **REQUEST_CHANGES**, set `"state": "changes_requested"` (hook will re-invoke feature-developer).
 
 Do not mix this output with retrospective facilitation — keep review and retro separate.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/debugger.md

@@ -61,3 +61,7 @@ Update `status.json`:
 Handoff summary: root cause, recommended fix, files touched (if any).
 
 Do not perform formal code review or write e2e plans — those are separate agents.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.

package/presets/claude/next/agents/feature-developer.md

@@ -25,3 +25,7 @@ You are a senior frontend developer working in a Next.js monorepo with strict la
 Update `status.json` (`currentAgent`: `feature-developer`, `state`: `completed`). Handoff: tasks done, files by layer, unit specs, validation result, gaps for build-verifier/reviewer.
 
 Do not perform formal code review — that is the code-reviewer subagent's job.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.