@rt-tools/agent-kit 0.2.0 → 0.4.0

package/assets/rules/spec-driven.md

@@ -0,0 +1,135 @@
+---
+name: spec-driven
+kind: rule
+law: project-documentation
+description: Правило под «Закон о документации проекта». Брать при правке docs/specs/**, docs/constitution/** и любого скила в .claude/skills. Называет три слоя — закон, правило, паттерн, — обязательные разделы, привязку к коду и связь сценариев с тестами. Готовый порядок действий — в паттернах spec-driven-domain и spec-driven-rule.
+---
+
+# Документация проекта — как это устроено здесь
+
+Правило под закон `docs/constitution/project-documentation.md`. Закон говорит, что должно
+быть верно про тексты; здесь — из каких слоёв они сложены в этом дереве и что сверяет машина.
+Формулировки — правило `doc-style` под тем же законом.
+
+## Как это называется здесь
+
+```
+ЗАКОН      docs/constitution/<закон>.md              — верен для любого приложения этого класса
+           docs/constitution/application/<закон>.md  — закон приложения: деньги, локали, доступ
+           о проекте не знает ничего: ни путей, ни имён файлов, ни привязок
+
+  ├─ ПРАВИЛО    .claude/skills/<правило>/SKILL.md   (kind: rule, law: <закон>)
+  │             привязывает закон к этому проекту; несколько правил на закон
+  │             .claude/skills/<правило>/implementation.md — привязка к коду
+  │
+  │  └─ ПАТТЕРН  .claude/skills/<правило>-<что>/SKILL.md   (kind: pattern, rule: <правило>)
+  │              готовый код и конкретные приёмы; минимум один на правило
+  │
+  └─ СПЕК ДОМЕНА  docs/specs/<домен>/
+                  как работает домен; объявляет законы, которые применяет
+
+СКИЛ БЕЗ ЗАКОНА  .claude/skills/<имя>/SKILL.md   (ни kind: rule, ни kind: pattern)
+                 стоит рядом с лестницей, а не в ней: он не про то, что должно быть
+                 верно в продукте, а про то, как здесь делается работа
+```
+
+Ссылки идут только снизу вверх: закон не ссылается ни на правило, ни на спек, ни на файл.
+
+Скил без закона — третий случай, и он законный. Витрина, генератор, работа с чужим сервисом,
+заведение самого скила: над таким нет утверждения о продукте, а значит нет и закона. Выдумывать
+ему закон, чтобы уложить в лестницу, нельзя — закон, у которого одно правило и ни одной статьи о
+продукте, разъезжается с остальными при первой же правке. Как такой скил заводится — скил
+`write-a-skill`.
+
+| В законе                        | Здесь                                                                                                |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| набор разделов                  | `REQUIRED_HEADINGS` для спека, «Статьи» для закона                                                   |
+| утверждение документа           | пункт `## Правила` в спеке, `## Статьи` в законе, `## Как закон применяется здесь` в правиле         |
+| место, где оно исполняется      | строка в `implementation.md` рядом: `` `файл:символ` ``                                              |
+| обещанное поведение             | сценарий `SC-<ПРЕФИКС>-<НОМЕР>` в `docs/specs/<домен>/scenarios.md`                                  |
+| открытый вопрос                 | `Q-N` — на него ссылаются из задачи на борде и из коммитов; номер после закрытия не переиспользуется |
+| законы, которые применяет домен | строка `**Законы:**` в шапке спека, именами в кавычках                                               |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Набор разделов спека задан заранее, и отсутствие раздела — отказ.** «Не применимо» —
+  законный ответ, отсутствие раздела — нет: сквозные требования вспоминаются постфактум
+  именно тогда, когда для них не заведено места.
+- **Каждое утверждение привязано к месту в коде, и связь сверяется в обе стороны.** Ключ
+  связи — сам текст утверждения, поэтому переформулировать его, забыв про привязку, нельзя.
+- **Привязка не ведёт в код, который никто не зовёт.** Символ, объявленный в своём файле и
+  больше нигде не встречающийся, местом исполнения не считается.
+- **Таблица процедур сверяется с декораторами в обе стороны.** Иначе процедура, которую домен
+  обслуживает, но забыл описать, видна только в декораторе.
+- **Код отказа принимается, только если он в домене бросается.** Коды выписывались по
+  замыслу, и на одном пути обещанный отказ не бросал никто.
+- **Префикс сценариев в домене один.** Второй префикс означает, что домен описан дважды.
+- **У закона обязателен раздел «Статьи», а кроме них он держит только открытые вопросы.**
+  Истории правок и доводов о выбранном когда-то варианте в законе нет: историю держит система
+  контроля версий, а довод с отвергнутой альтернативой — свойство работы, и место ему в
+  «Ловушках» правила. Закрытый вопрос из закона уходит, а пустой раздел ради заголовка
+  проверку всё равно проходил.
+- **Закон, назвавший файл проекта, — отказ.** Путям и привязкам место в правиле: иначе закон
+  нельзя ни прочитать без знания дерева, ни применить на другом приложении.
+- **Правило объявляет закон, под который написано.** Правило без закона — набор приёмов, из
+  которого не видно, что именно должно быть верно.
+- **Слоёв законов два, а имя закона одно на оба.** Общий лежит в корне конституции, закон
+  приложения — в `application/`; ни `law:`, ни `**Законы:**` слоя не называют, поэтому имена
+  законов уникальны по всему дереву конституции.
+- **Спек объявляет законы, которые применяет, и связь сверяется в обе стороны.** Закон,
+  названный в тексте спека, обязан стоять в шапке: иначе по закону не узнать, какие домены
+  на нём стоят.
+
+## Чего из закона здесь нет
+
+Закон, которого не применяет ни один спек, отказом не считается: законы про устройство кода,
+поставку и проверяемость доменов не касаются вовсе. Порядок «сначала описание, потом код»
+держится договорённостью — это `Q-PD-3` в законе.
+
+Таблицы состояний экрана не сверяются ничем. `check:specs` знает сценарии против заголовков
+тестов, правила против якорей, процедуры против декораторов и коды отказа против бросков —
+строка таблицы состояний не привязана ни к чему и проходит зелёной, даже когда код в
+названное состояние не попадает. Состояние «проверка не загрузилась» стояло в таблицах двух
+доменов раньше, чем код научился в него приходить, и всё это время читалось описанием
+работающего.
+
+## Паттерны
+
+- `spec-driven-domain` — заведение и правка спека домена, сценарии, привязка.
+- `spec-driven-rule` — заведение закона, правила и паттерна.
+
+## Ловушки
+
+- **`tasks.md` в спеке не заводить.** Шаги — артефакт сессии, им место в ветке или в описании
+  PR. Как только в директории появляются «шаги», спек снова становится планом и умирает после
+  мержа.
+- **Спек описывает установившееся, а не предстоящее.** Единственное место, где он говорит о
+  будущем, — `proposed/<фича>/`. После выкатки его текст вливается в спек домена, директория
+  удаляется, идентификаторы сценариев не меняются.
+- **Семантику полей не сверяет ничто.** Проверка знает имена процедур, коды отказа и связь
+  сценариев с тестами; что означает пустое поле — не знает. Правка `.proto` поэтому тянет
+  спеки всех доменов, чьи процедуры она задела, в той же ветке.
+- **Живость символа считается совпадением имени по всему дереву, а не вызовом.** Символу
+  хватает второго упоминания где угодно — в чужом поле с тем же именем, в атрибуте разметки.
+  Место, где правило исполняется на самом деле, подтверждается только чтением кода.
+- **Якорь в `tools/*.mjs` сверяется почти ничем:** живость считается только для `.ts`, а
+  исходники обходятся по `apps`, `libs` и `prisma`. Правило, привязанное к проверке, поэтому
+  читается вместе с её телом.
+- **Зелёная проверка не значит, что структура верна.** Спутники с привязкой сначала лежали
+  рядом с законами, и проверка была зелёной именно потому, что структура совпадала с тем,
+  чего проверка сама и ждала.
+- **Конфликт мержа в спеке разрешается сохранением обеих сторон, а не выбором одной.** Две
+  ветки дописывают в конец одних и тех же списков — сценариев, правил, строк привязки, — и
+  обе стороны верны: конфликт здесь не спор, а две дописи в одно место. Номера сценариев при
+  разрешении не пересчитываются: идентификатор — ключ связи с тестами, и сдвиг номеров рвёт
+  сверку у соседей, которых правка не касалась. Порядок сохранённых сторон держится
+  одинаковым в `spec.md`, `scenarios.md` и `implementation.md`: иначе правило, его сценарий и
+  его привязка перестают находиться друг по другу. После разрешения гоняется
+  `npm run check:specs` — конфликт в спеке кода не задевает, и ни сборка, ни линтеры его не
+  увидят.

package/assets/rules/styling-bem.md

@@ -0,0 +1,74 @@
+---
+name: styling-bem
+kind: rule
+law: frontend-application
+description: Правило под «Закон о фронтовом приложении». Брать при правке любого *.scss и шаблона компонента. Называет директивы BEM, токены оформления, общий слой раскладки приложения и проверку класса без правила. Готовый код — в паттернах styling-bem-layout и styling-bem-component.
+---
+
+# Оформление — как это устроено здесь
+
+Правило под закон `docs/constitution/frontend-application.md`. Закон говорит, что должно быть
+верно; здесь — чем это названо в этом дереве и где лежит. Раскладка файла компонента —
+`component-structure`, состояние — `angular-patterns`, окружение браузера —
+`platform-access`, слой обращения к серверу — `api-layer`. Все пять под одним законом.
+
+## Как это называется здесь
+
+| В законе                        | Здесь                                                                                                                                        |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| общий набор значений оформления | шкалы кита `--rt-*`; своё поверх них — `--vm-*` в `styles.scss` приложения                                                                   |
+| класс в разметке                | директивы `rtBlock` и `rtElem` из `@rt-tools`, а не строка в атрибуте                                                                        |
+| правило стилей                  | объявление `&__<элемент>` в `.scss` — своём или в общем слое приложения                                                                      |
+| общий слой раскладки            | `apps/<app>/src/styles/`: `<префикс>-page`, `<префикс>-form`, `<префикс>-panel`, `<префикс>-window` у админки, `<префикс>-site-page` у сайта |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Оформление берётся токеном `--rt-*`, а не пишется значением на месте.** Составные
+  значения — `box-shadow`, `text-shadow` — берутся готовым токеном целиком, а не собираются
+  из частей.
+- **У каждого класса элемента есть своё правило стилей.** Класс без правила выглядит рабочим
+  и молча ничего не делает.
+- **Класс ставится директивой, а не строкой в атрибуте.** Имя блока `rtElem` получает
+  инъекцией от ближайшего предка с `rtBlock`, и повторить этот разбор по тексту шаблона нечем.
+- **Раскладка объявлена в общем слое приложения, а не в стилях экрана.** У компонента экрана
+  вне кита файл стилей по умолчанию пустой.
+- **Предупреждение stylelint роняет прогон наравне с ошибкой.** `!important` объявлен
+  предупреждением, а прогон идёт с `--max-warnings 0`: иначе запрет читается как пожелание —
+  два таких предупреждения лежали в дереве, а `npm run stylelint` возвращал ноль и гейтом не был.
+
+## Чего из закона здесь нет
+
+Проверка «класс без правила» считает совпадение по имени элемента, а не по паре «блок —
+элемент»: класс, у которого правило есть, но у чужого блока, она пропускает. Обратное
+направление — снятие правила у живого класса — не проверяется вовсе и ловится чтением шаблона.
+
+## Паттерны
+
+- `styling-bem-layout` — экран на общем слое раскладки, блоки приложения.
+- `styling-bem-component` — стили компонента кита, `:host`, модификаторы, язык оформления сайта.
+
+## Ловушки
+
+- **`rtElem` без предка с `rtBlock` роняет отрисовку в рантайме** — сборка и линт молчат.
+- **`rtBlock` на `<ng-container>` класса не ставит вовсе:** узел это комментарий, и имя блока
+  он только объявляет потомкам. Класс блока экрана вешает хост через `host: { class: … }`.
+- **`justify-content: center` во flex-контейнере с `overflow-x` уводит первые элементы за
+  нулевой скролл** — доскроллить до них невозможно. В прокручиваемых лентах —
+  `justify-content: safe center`.
+- **`scrollbar-gutter: stable` на корне не заводить:** резерв под полосу прокрутки сужает
+  содержащий блок для `position: fixed`, и попап, выровненный по правому краю, встаёт на
+  ширину резерва левее своей кнопки.
+- **`& + :host` невалиден:** изнутри компонента до соседнего хоста не дотянуться. Разделитель
+  между повторяющимися хостами — `:host(:not(:first-of-type))`.
+- **`[attr.aria-disabled]` визуального состояния не даёт:** браузер стилизует `:disabled`, но
+  атрибуты `aria-*` — нет. К каждому `aria-disabled` заводится правило `[aria-disabled='true']`.
+- **Гарнитуру с `body` элементы формы не наследуют:** браузер задаёт `button`, `input`,
+  `select` и `textarea` свой шрифт. Наследование включено глобально — сбрасывать его нельзя.
+- **Комментарии-выключатели stylelint не ставятся.** Селекторы объединяются вложенностью.
+- **При переносе стилей новых объявлений не появляется** — только перемещение существующих.

package/assets/rules/task-flow.md

@@ -0,0 +1,110 @@
+---
+name: task-flow
+kind: rule
+law: work-conduct
+description: Правило под «Закон о ведении работы». Брать в начале любой работы от владельца, при правке docs/tasks/**, docs/specs/*/proposed/** и при возвращении к незаконченной задаче. Называет разбор просьбы до первой правки, папку задачи по имени ветки, договорённость о продукте до кода, шесть обязательных вопросов и разбор папки при закрытии. Готовый порядок — в паттернах task-flow-start, task-flow-resume и task-flow-close.
+---
+
+# Ведение работы — как это устроено здесь
+
+Правило под закон `docs/constitution/work-conduct.md`. Закон говорит, что должно быть верно
+про ход работы; здесь — чем это названо в этом дереве, где лежит и что из закона у нас не
+проверяется.
+
+## Как это называется здесь
+
+| В законе                                      | Здесь                                                                                                                         |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| просьба владельца                             | то, с чего начинается работа; разбирается командой `/grill-me` до первой правки                                               |
+| понимание, записанное там, где идёт работа    | `docs/tasks/<ветка>/grill.md` — просьба дословно, ответы владельца его словами, решения с доводами                            |
+| замысел                                       | `docs/tasks/<ветка>/plan.md` — след задачи и этапы с признаками готовности; после написания не правится                       |
+| ход работы                                    | `docs/tasks/<ветка>/progress.md` — «Где стоим», решения по ходу, записи заходов; единственное место, где отмечается сделанное |
+| договорённость о продукте, записанная до кода | `docs/specs/<домен>/proposed/<фича>/` — спек фичи; переживает мерж и вливается в спек домена                                  |
+| работа шире одной ветки                       | файл в `docs/plans/`, один на линию работ: порядок задач и зависимости между ними                                             |
+| папка задачи до заведения задачи              | `docs/tasks/_draft-<slug>/` — вне истории, пока номера нет                                                                    |
+| разведка                                      | заход `Explore` или `general-purpose` до первого вопроса владельцу                                                            |
+| разбор замысла ролями                         | `.claude/workflows/plan.js` — нужность, договорённость, критика, замысел                                                      |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Правка кода приложения отбивается, пока на диске нет замысла.** Гард требует папку задачи
+  по имени ветки, `plan.md` в ней и названную в его шапке договорённость о продукте.
+- **Договорённость требуется по путям правки, а не по оценке задачи.** `apps/**` и `libs/**`
+  — признак; правила, тексты, обвязка и зависимости под него не подпадают. Обход — строка
+  `**Поведение:** не меняется — <причина владельца>` в замысле; пустая причина не
+  принимается.
+- **Состояние незаконченной работы приходит в контекст на запуске сессии.** Замысел и ход
+  работы отдаются целиком, разбор просьбы — путём. Ветка вида `<КЛЮЧ>-*` без папки даёт
+  предупреждение с готовой командой, но сессию не рвёт.
+- **Сделанное отмечается только в ходе работы.** «Где стоим» перезаписывается каждым заходом,
+  а не дописывается: это первое, что читает следующий заход.
+- **Папка задачи заводится черновиком и получает номер командой.** До конца разбора
+  неизвестно, сколько задач из него выйдет, поэтому номер не может быть первым;
+  `npm run task:new` переименовывает черновик и проставляет шапку замысла.
+- **Брошенный разбор виден.** Черновик старше недели перечисляет сверка очереди работ —
+  задачи за ним ещё нет, и спросить о нём некого.
+- **Договорённость вливается в спек домена последним коммитом отчёта.** К этому моменту код
+  написан, привязки известны, и в главной ветке директория `proposed/` не появляется вовсе.
+  Готовые к вливанию перечисляет `npm run check:specs`.
+- **Папка закрытой задачи разбирается, а не переносится целиком.** В `docs/archive/` уезжает
+  то, что объясняет состоявшееся решение; остальное удаляется. Неразобранную ловит сверка
+  очереди работ.
+
+## Чего из закона здесь нет
+
+Полноту записанного понимания не проверяет ничто, и проверки на неё не будет: машине видно
+наличие записи, но не то, что в ней закрыты все пробелы. Разбор из одной строки проходит гард
+так же, как разбор на сто. То же с вопросом, который стоило задать и не задали, — он не
+оставляет следа. Оба разобраны решениями в законе: судит владелец.
+
+Гард судит по путям правки, а не по тому, меняет ли работа поведение на самом деле.
+Рефакторинг, снаружи не видный, упирается в требование договорённости и проходит обходом с
+причиной. Своего признака рефакторингу не заводится: оценку «поведение не меняется»
+назначал бы тот, кому она мешает.
+
+Ничто из самого разбора не проверяется, и всё это держится памятью того, кто его ведёт.
+Разговор с владельцем инструментом не является — гард видит правку файла и ничего не знает
+ни о том, была ли разведка до первого вопроса, ни о том, задан ли каждый из шести
+обязательных вопросов, ни о том, ответил ли на них владелец. Образец разбора перечисляет их
+таблицей, но пустая таблица проходит так же, как заполненная.
+
+Неизменность замысла не стережёт ничто: `plan.md` правится тем же инструментом, что и
+остальные тексты, и правка по ходу отличима от первоначальной записи только по истории.
+Держится это тем же, чем и порядок разбора.
+
+Разбор папки при закрытии не проверяется по существу: сверка очереди работ видит, что папка
+закрытой задачи лежит на месте, но не судит, что из неё стоило увезти в архив.
+
+## Паттерны
+
+- `task-flow-start` — разведка, разбор, договорённость, замысел, задача и ветка.
+- `task-flow-resume` — возвращение к незаконченной работе новым заходом.
+- `task-flow-close` — вливание договорённости, разбор папки, переезд в архив.
+
+## Ловушки
+
+- **Папка называется именем ветки, один в один.** Хук запуска ищет её по
+  `git branch --show-current`, и папка, названная иначе, не находится ничем: работа идёт с
+  пустым контекстом, а владельца просят пересказать то, что уже записано.
+- **Разбор просьбы задним числом не переписывается.** Пересказ незаметно подгоняется под уже
+  сделанное, и сверять результат становится не с чем. Решение, изменённое по ходу, дописывается
+  в ход работы, а не правится в разборе.
+- **Договорённость о продукте не кладётся в папку задачи.** Папка умирает с мержем, а
+  договорённость обязана его пережить: её сценарии получают номера в общей нумерации домена,
+  и на них ссылаются заголовки тестов. Обратное тоже верно — ход работы не кладётся в
+  `proposed/`: спек, в котором завелись шаги, снова становится планом и умирает после мержа.
+- **Меню вариантов на разборе годится только для выбора значения из закрытого набора.** Пока
+  постановка вопроса не подтверждена, спрашивается прозой: у меню нет строки «вопрос не тот».
+  Выбор слова, имени и термина узким вопросом не является никогда.
+- **Субагент вопросов владельцу не задаёт.** Ни роли, ни конвейер до него не достучатся —
+  они возвращают текст главному агенту. Поэтому разбор ведёт главный агент, а роли стоят по
+  обе стороны от него.
+- **Слово для нового понятия берётся из `docs/GLOSSARY.md` или заводится там же.** Третий файл
+  папки задачи называется `progress.md`, а не `journal.md`, ровно поэтому: журнал в этом
+  дереве один, и он другой.

package/assets/rules/testing.md

@@ -0,0 +1,100 @@
+---
+name: testing
+kind: rule
+law: verifiability
+description: Правило под «Закон о проверяемости». Брать при правке любого *.spec.ts и всего, что лежит в apps/site-e2e и apps/admin-e2e. Называет Vitest и Playwright, идентификатор сценария в заголовке, вынос решения в чистую функцию и то, что закрывается сквозной спекой. Готовый код — в паттернах testing-unit и testing-e2e.
+---
+
+# Проверяемость — как это устроено здесь
+
+Правило под закон `docs/constitution/verifiability.md`. Закон говорит, что считается
+подтверждением; здесь — чем это названо в этом дереве, где лежит и что из закона у нас не
+применяется. Проверка работающего приложения глазами и замером — правило
+`browser-verification` под тем же законом.
+
+## Как это называется здесь
+
+| В законе                   | Здесь                                                                            |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| сценарий                   | `SC-<ПРЕФИКС>-<НОМЕР>` в `docs/specs/<домен>/scenarios.md`                       |
+| тест                       | `it(...)` в `*.spec.ts` рядом с исходником — Vitest; сквозная спека — Playwright |
+| сводка покрытия            | вывод `npm run check:specs`: покрыто, частично, без тестов                       |
+| отметка непокрытого        | строка `Не покрыто: <причина>` внутри блока сценария                             |
+| отметка неполного покрытия | строка `Покрытие: частичное — <чего не хватает>`                                 |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Идентификатор сценария стоит в начале заголовка теста, через тире.** Один сценарий
+  проверяется несколькими тестами, один тест закрывает несколько сценариев.
+- **Сценарий без теста несёт отметку с причиной.** Пустая отметка не принимается, а отметка
+  при существующем тесте — отказ: она означает, что долг закрыли, а отметку не сняли.
+- **Тест, идущий не тем путём, что пользователь, помечается частичным покрытием.** В сводку
+  он попадает долгом, а не покрытием.
+- **Сценарий, чьё «Тогда» называет человека и то, что он видит, закрывается сквозным тестом.**
+  Юнит на тот же расчёт остаётся долгом: между верным решением и тем, что человек его видит,
+  лежит всё, чего юнит не касался.
+- **Сквозной тест, погашенный переменной окружения, покрытием не считается.** Выключатель по
+  состоянию стенда — пропуск случая, выключатель по переменной — невыполненный тест.
+- **Упоминание в тесте сценария, которого в спеках нет, роняет проверку.** Так ловится
+  переименованный или выкинутый сценарий: тесты при этом остаются зелёными.
+- **Решение выносится в чистую функцию и проверяется вызовом.** Компонент и сервис остаются
+  тонкой обёрткой и отдельно не проверяются, пока своего ветвления у них нет.
+- **Процедура Connect проверяется вызовом своего метода с рукописным двойником базы.**
+  Контейнер и роутер поднимать не надо: спека проверяет решение, а не раскладку полей.
+- **Спека, необратимо меняющая данные стенда, выключена по умолчанию.** `BASE_URL` уводит
+  прогон одной переменной, и без выключателя такая спека правила бы данные чужого стенда.
+- **Спеки, которым нужен nginx перед приложением, просыпаются вместе с `BASE_URL`.** Голый
+  сервер отдачи страниц их не проходит: перенаправления живут в конфиге прокси.
+- **Правило линтера, которое запрещает принятый здесь приём, выключают в конфиге, а не
+  обходят в каждом тесте.** Выключатель теста — приём этого дерева, а
+  `playwright/no-skipped-test` запретил бы его сразу в шестидесяти пяти местах. Рядом со
+  строкой отключения пишут причину, а точечный `eslint-disable` остаётся для того, что
+  запрещено по делу.
+
+## Чего из закона здесь нет
+
+Полнота теста не проверяется: сверка судит путь — сквозной он или юнит, — но не то, сколько
+из обещанного тест на этом пути закрыл. Признак пути читается из слов «Тогда» и нарочно
+молчалив: сценарий, чьё обещание человека не называет, под него не подпадает вовсе, и
+отметку неполноты там по-прежнему ставит рука. Договорённостей о подмене модулей тоже нет:
+`vi.mock` в дереве не встречается ни разу, и двойник пишется руками.
+
+## Паттерны
+
+- `testing-unit` — тест на чистую функцию, на процедуру Connect и разовый тест-доказательство,
+  который не коммитится.
+- `testing-e2e` — прогон сквозных тестов, стенд под настоящим nginx, выключатели.
+
+## Ловушки
+
+- **Зелёный `nx test <проект>` не значит, что хоть один файл исполнялся.** Либа без своего
+  `vitest.config.mts` не запускает ничего — так тесты домена броней не запускались ни разу.
+  Либа с конфигом, но без единого `*.spec.ts`, проходит зелёной из-за `passWithNoTests: true`,
+  который стоит во всех 203 конфигах дерева, и на глаз эти два случая неотличимы: в обоих
+  прогон успешен. Без единого теста живут 131 либа из 203 — почти две трети. Перед правкой в
+  незнакомой либе проверяется, есть ли в ней хоть один `*.spec.ts`; если нет — первый
+  заводится этой же правкой, а не откладывается: откладывать здесь не с чего, долг уже
+  накоплен. Пересчёт: `for d in $(find libs -name vitest.config.mts -exec dirname {} \;); do
+[ -z "$(find "$d" -name '*.spec.ts')" ] && echo "$d"; done | wc -l`.
+- **«Executable doesn't exist» — состояние машины, а не дефект правки.** Установлен только
+  chromium, `firefox` и `webkit` падают всегда: гонять `--project=chromium`, узкий экран —
+  `--project=mobile-chrome`. Та же ошибка приходит после смены версии Playwright: браузер
+  ставится под конкретную версию, и после подъёма нужен повторный
+  `npx playwright install chromium`. Девять тестов так и упали, и это выглядело регрессией
+  обновления.
+- **Первому прогону сразу после установки браузера верить нельзя.** Два падения `admin-e2e`
+  не повторились ни при отдельном прогоне тех же тестов, ни при втором полном. Такой прогон
+  повторяют, а выводы делают по второму.
+- Сквозные тесты админки без `E2E_ADMIN_EMAIL` и `E2E_ADMIN_PASSWORD` пропускаются молча — в
+  отчёте они значатся `skipped`, и прогон выглядит успешным.
+- **Справочник флоу вторых сценариев не заводит.** В `docs/E2E_<ДОМЕН>_FLOWS.md` кладут то,
+  чего в спеке домена нет и быть не должно: `qa-dataid` элементов, состояния разметки, ловушки
+  стенда. Обещанное поведение остаётся сценарием в `scenarios.md`: если списать его во второе
+  место, копии разойдутся молча — `npm run check:specs` этого не увидит.
+- `npx nx serve` проверкой не является: это шаг из правила `browser-verification`, а не тест.

package/assets/rules/translations.md

@@ -0,0 +1,69 @@
+---
+name: translations
+kind: rule
+law: locales
+description: Правило под «Закон о локалях и переводах». Брать при заведении любого видимого текста, правке словарей libs/common/i18n, префиксов локалей сайта и перевода контента объекта. Называет восемь локалей, Transloco, производные переводы и начальную валюту локали. Готовый код — в паттерне translations-key.
+---
+
+# Локали и переводы — как это устроено здесь
+
+Правило под закон `docs/constitution/application/locales.md`. Закон говорит, что должно быть верно;
+здесь — чем это названо в этом дереве и где лежит. Разметка сайта для поиска — `seo` под
+своим законом.
+
+## Как это называется здесь
+
+| В законе             | Здесь                                                                                               |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
+| локаль сайта         | одна из восьми: `en`, `ru`, `de`, `zh-Hans`, `zh-Hant`, `ko`, `th`, `hi`                            |
+| локаль по умолчанию  | `en` — отдаётся из корня, без префикса в адресе                                                     |
+| локаль ввода         | `source_locale` в запросе сохранения объекта; берётся из языка админки                              |
+| словарь              | JSON-словари Transloco в `libs/common/i18n/src/lib/dictionaries/<локаль>/`, разложенные по разделам |
+| перевод контента     | jsonb по локалям в базе, заполняется бэкендом                                                       |
+| подстановка в шаблон | `\| transloco` в разметке, `translateSignal` в классе                                               |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Локаль по умолчанию отдаётся из корня, остальные семь — из-под префикса пути.**
+- **Видимый человеку текст берётся из словаря и заводится во всех локалях перевода.** Ключ,
+  потерянный в одной локали, гость видит на кнопке как есть.
+- **Пустой перевод считается пропуском, а не переводом.** Запасной словарь подставляется
+  только на отсутствующий ключ, а пустую строку отдаёт как есть.
+- **Переводы контента производные: владелец пишет на своём языке, остальные семь локалей
+  заполняет бэкенд при сохранении.** Табов локалей в формах админки нет — правка вручную всё
+  равно была бы перезаписана.
+- **Отказ перевода сохранение не срывает.** Текст на локали ввода записывается, прежние
+  переводы остаются, и владелец видит предупреждение, а не сообщение об успехе.
+- **Локаль, для которой перевода не пришло, сохраняет прежнее значение.**
+- **Язык админки выбирает владелец, и выбор живёт в его профиле.** Он же уходит в локаль
+  ввода при сохранении объекта.
+- **У локали есть начальная валюта показа.** Дальше валюту выбирает гость, и его выбор
+  сильнее умолчания локали.
+
+## Чего из закона здесь нет
+
+Страница не показывает, что перевод устарел: владелец правку сохранил, провайдер отказал —
+и гость по-прежнему видит старый текст. Это `Q-L-1` в законе.
+
+## Паттерны
+
+- `translations-key` — заведение ключа во всех локалях перевода и подстановка в разметку.
+
+## Ловушки
+
+- **Полноту словарей держит не рантайм, а тест.** `nx test common-i18n` роняет сборку на
+  недостающем или пустом ключе; дозаполнить недостающее — `npm run i18n:fill`.
+- **Наборы ключей сверяются внутри раздела**, а не по всему словарю сразу: словари разложены
+  на общий, сайт, письма и админку.
+- **Перевод контента идёт до транзакции сохранения:** страница объекта не должна оказаться
+  наполовину переведённой. Кэш сбрасывается после записи и один раз.
+- **Без ключа `ANTHROPIC_API_KEY` сохранение проходит,** но переводы остаются прежними, и
+  владелец видит предупреждение `propertySaveTranslationFailed`.
+- Новый маршрут сайта без ветки под каждую локаль существует только в локали по умолчанию:
+  `/de/<путь>` отдаст 404 и поисковику, и гостю.

package/assets/rules/typescript-conventions.md

@@ -0,0 +1,76 @@
+---
+name: typescript-conventions
+kind: rule
+law: code-structure
+description: Правило под «Закон об устройстве кода». Брать при правке любого .ts, кроме компонента, сервиса, директивы, пайпа, гарда и интерцептора — строгая типизация, модификаторы доступа, приватные поля, имена файлов, префиксы, перечисления, запрет приведения в маппере, процедуры Connect на бэкенде. Готовый код процедуры — в паттерне ts-procedure.
+---
+
+# Устройство кода — как это устроено здесь
+
+Правило под закон `docs/constitution/code-structure.md`. Закон говорит, что должно быть верно
+про объявления; здесь — как это записано в этом дереве.
+
+## Как это называется здесь
+
+| В законе                    | Здесь                                                     |
+| --------------------------- | --------------------------------------------------------- |
+| признак рода в имени        | префикс: `I` у интерфейса, `E` у перечисления, `T` у типа |
+| источник, за которым следят | суффикс `$` у наблюдаемого и `Source` у субъекта          |
+| приватное поле              | `#field`, а не `private field`                            |
+| процедура бэкенда           | класс с меткой `@ConnectProcedure()`, один на процедуру   |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Род объявления виден по префиксу имени, и это держат три правила линтера.** У интерфейса,
+  у типа и у перечисления свои; все три подняты для всех `.ts`.
+- **Источник, за которым следят, назван суффиксом.** Субъект и наблюдаемое, поднятое из него,
+  различаются в месте использования, а не переходом к объявлению.
+- **Суффикс имени файла находит в нём обещанное объявление.** Список суффиксов закрыт: слово,
+  которого в нём нет, суффиксом не считается, и такой файл правило не судит.
+- **Тип берётся из того пакета, где объявлен.** Своя копия чужого типа расходится с оригиналом
+  молча, а компилируется из них только одна.
+- **Двухступенчатое приведение `as unknown as` запрещено правилом линтера.** Вместо него —
+  честный тип, сужение проверкой или чтение поля формой (`Reflect.get`); место, где иначе
+  нельзя, помечается точечным отключением с причиной в той же строке.
+- **Отметка об устаревании ставится вместе с обходом потребителей.** Все правила
+  `eslint-plugin-sonarjs` подняты до отказа разом, и пометка на типе красит каждое место, где
+  его ещё зовут: один `@deprecated` на файл дал семнадцать замечаний в чужих доменах.
+
+## Чего из закона здесь нет
+
+Одноступенчатое приведение остаётся непроверенным — это `Q-CS-4` в законе: из семидесяти
+шести приведений восемь обязательны, и общий запрет отбивал бы их.
+
+Тесты из-под запрета выведены целиком: рукописный двойник базы — принятый здесь приём, и
+запрет пришлось бы обходить в каждом из тридцати пяти.
+
+Правило имён файлов судит обещание, а не его отсутствие: `menu.items.ts` и `sign-in.ts` под
+него не подпадают вовсе — это `Q-CS-3` в законе. Из двух принятых здесь форм перевода
+сущности — класс на фронте и чистые функции на бэкенде — правило принимает обе: оно судит
+имя, а не устройство, и что форм две, остаётся вопросом `Q-S-1` в законе об общем коде.
+
+На `libs/api/**` и `apps/api/**` правило действует целиком, а вот сигнальный API и `inject`
+туда не относятся: там NestJS с конструкторным DI.
+
+## Паттерны
+
+- `ts-procedure` — завести процедуру Connect на бэкенде: класс, метка, право, регистрация.
+
+## Ловушки
+
+- Приведение через `as Type` в маппере запрещено, но не стережётся ничем: оно принимает любое
+  значение и компилируется. Вместо него — `this.typeCast`.
+- Неиспользуемый параметр убирается, а не переименовывается: подчёркивание перед именем прячет
+  замечание, но параметр остаётся в сигнатуре.
+- Агрегат Prisma своим типом не аннотируется: сгенерированный тип у него шире, чем результат
+  выборки, и аннотация врёт.
+- Своё правило линтера включается вместе с переводом всех, кого оно ловит: включённое поверх
+  накопленного даёт красный прогон на файлах, которых правка не касалась.
+- `#field` виден только внутри класса и не принимается `viewChild` — там поле объявляется
+  `protected`.