@rt-tools/agent-kit 0.2.0 → 0.3.0

package/assets/rules/platform-access.md

@@ -0,0 +1,49 @@
+---
+name: platform-access
+kind: rule
+law: frontend-application
+description: Правило под закон «Фронтовое приложение». Брать, когда правка задевает глобальный объект или среду исполнения — окно, глобальную область, признак браузера, хранилище, наблюдатели. Глобальное приходит внедрением, среда проверяется службой, а не наличием глобала. Не действует на серверной стороне. Готовый код — в паттерне platform-access-di. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Окружение браузера — каким приёмом
+
+Правило под закон `{{lawsDir}}/frontend-application.md`. Закон говорит, что должно быть верно;
+здесь — каким приёмом прямое обращение к глобальному объекту заменяется. Какими токенами и
+службами это названо и откуда они приходят — `implementation.md` рядом. Состояние —
+`angular-patterns`, файл компонента — `component-structure`, оформление — `styling-bem`, слой
+обращения к серверу — `api-layer`. Все пять под одним законом.
+
+Правило про фронт: на серверной стороне своя среда, и ничего из перечисленного к ней не
+относится.
+
+## Когда берётся
+
+Правка задевает глобальный объект, признак среды, хранилище браузера или наблюдателя за
+разметкой.
+
+## Что здесь действует
+
+- **Глобальный объект приходит внедрением, а не берётся напрямую.** Тип уточняется приведением
+  к глобальной области: конструкторы наблюдателей объявлены на ней, а не на интерфейсе окна.
+- **Среда проверяется службой, а не наличием глобала.** Проверка по наличию верна случайно и
+  ломается на первой же среде, где глобал подставлен.
+- **Место прямого доступа заводится только с согласия владельца.** Их немного, и каждое
+  осознанно: скрипт, работающий до подъёма приложения, обработчик отказа подъёма и код,
+  исполняемый внутри страницы в сквозной спеке. Новое в этот список не добавляется молча.
+
+## Паттерны
+
+- `platform-access-di` — готовые внедрения, приведение типа, чистые функции, проверка среды.
+
+## Ловушки
+
+- **Фабрика токена окна бросает отказ, когда у документа нет представления.** Под отдачей
+  страницы сервером представление есть, и внедрение полем класса безопасно, но служба,
+  обязанная работать без разметки вовсе, берёт окно внутри метода под проверкой среды.
+- **После правки, добавляющей окно в службу, которая создаётся на подъёме, нужна не только
+  сборка, но и поднятый сервер отдачи страниц.** Падение видно только там.
+- **Вокруг хранилища проверка среды не нужна.** Служба хранилища и так уходит в память вне
+  браузера, и лишняя проверка вокруг чтения и записи — мёртвый код.
+- **В чистых функциях внедрения нет** — окно принимается параметром, а внедряет его вызывающий.
+- **Подготавливать состояние сквозной спеки записью в хранилище нельзя** — спека проходит те же
+  шаги, что и пользователь.

package/assets/rules/reuse-first.md

@@ -0,0 +1,69 @@
+---
+name: reuse-first
+kind: rule
+law: reuse-first
+description: Правило под закон «Единообразие приложения». Брать перед заведением любого нового экрана, компонента, поля, стора, сервиса, переводчика моделей или обработчика — на что опираться, по каким признакам видно, что готовое обошли. Что делать, когда готового не хватило, — в паттерне reuse-first-extend. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Единообразие — каким приёмом
+
+Правило под закон `{{lawsDir}}/reuse-first.md`. Закон говорит, что одинаковые вещи ведут себя
+одинаково; здесь — каким приёмом это держится. На какие именно источники вида и основы это
+дерево опирается — `implementation.md` рядом.
+
+## Когда берётся
+
+Заведение нового файла: экрана, компонента, поля, стора, сервиса, переводчика моделей,
+обработчика серверной стороны. Правило берётся **до** первой строки, а не после.
+
+## Что здесь действует
+
+- **Источник вида выбирается по приложению, а не по привычке.** У дерева может быть больше
+  одного источника — свой у каждого приложения; перепутанный приносит на экран форму, которой в
+  этом приложении больше нигде нет.
+- **Работа начинается с чтения готового, а не с чистого файла.** Сначала находится опора —
+  готовый компонент, базовый класс, образец в соседнем домене, — потом пишется своё поверх неё.
+  Соседний домен читается целиком: приём, который кажется новым, обычно уже написан, а
+  переименованный при переносе он перестаёт узнаваться.
+- **Свой примитив и своя основа заводятся только с явного одобрения владельца.** Спрашивается
+  это до того, как написан первый файл, а не после.
+- **Панель правки записи наследует общую основу, а не собирается своей разметкой.** Тогда она
+  открывается, закрывается и спрашивает про несохранённое одинаково во всех разделах.
+- **Об удаче и об отказе сообщает общая шина, а не своя разметка на экране.** Своё сообщение
+  расходится с соседним видом, местом и временем показа.
+- **Компонент объявляется отдельными файлами разметки и стилей.** Шаблон и стили внутри
+  декоратора, атрибут стиля в разметке и правка размеров привязкой к стилю — это оформление, до
+  которого не дотянется ни источник вида, ни линтер стилей.
+- **У компонента экрана файл стилей по умолчанию пустой.** Раскладка объявлена один раз в общем
+  слое приложения, а экран её только применяет.
+- **Готовое расширяется, а не клонируется рядом.** Недостающий вариант заводится в источнике
+  вида или в базовом классе, и его видят остальные экраны. Клон, написанный рядом, забирает
+  правки на себя и расходится с оригиналом с первой же.
+
+## Паттерны
+
+- `reuse-first-extend` — что делать, когда готового не хватило: расширить готовое, объявить
+  разовое отступление маркером, снять его.
+
+## Признаки, по которым видно, что готовое обошли
+
+- в шаблоне фичи стоит нативный элемент ввода, кнопки, выбора, таблицы или диалога;
+- отказ или предупреждение собраны руками — своя область оповещения вместо готового сообщения;
+- в стилях фичи появились перекрытие всего экрана, своя вуаль, слой поверх всего, свои кадры
+  вращения или мерцания;
+- в файле стилей экрана объявлена раскладка, а не только его собственные отличия;
+- компонент сам реализует договор поля формы, вместо того чтобы наследовать основу;
+- имя файла кончается на род готового компонента — кнопку, поле, диалог, таблицу — и лежит вне
+  источника вида;
+- переводчик моделей переводит поля вручную, минуя общую основу;
+- обработчик серверной стороны объявлен без общей метки.
+
+## Ловушки
+
+- **Перенос переизобретением не считается.** Строка, которая уже лежала в дереве, при переезде
+  меняет отступ, оставаясь тем же кодом; сверка идёт без отступов, иначе каждый переезд читался
+  бы как новый код.
+- **Ответ, данный до чтения образца, образец отменяет.** Согласованная форма переигрывается,
+  как только находится готовая: договорённость слабее того, что уже написано и работает.
+- **Подсказка, зовущая за ненаписанным, останавливает работу.** Пока свой вариант не написан,
+  правило зовёт за готовым — а не за тем, что «должно появиться».

package/assets/rules/seo.md

@@ -0,0 +1,50 @@
+---
+name: seo
+kind: rule
+law: search-visibility
+description: Правило под закон «Видимость в поиске». Брать при любой правке, доходящей до разметки публичной части — шаблоны страниц, заголовок и описание, структурированные данные, канонический адрес, языковые ссылки, маршруты, карта сайта, правила обхода, конфиг прокси. Готовый код — в паттернах seo-page и seo-verify. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Видимость в поиске — каким приёмом
+
+Правило под закон `{{lawsDir}}/search-visibility.md`. Закон говорит, что должно быть верно;
+здесь — каким приёмом это держится. Какие локали набраны, где лежит служба тегов и чем зовётся
+канонический путь — `implementation.md` рядом.
+
+## Когда берётся
+
+Любая правка, доходящая до разметки публичной части: шаблон страницы, теги в голове документа,
+структурированные данные, маршруты, карта сайта, правила обхода, конфиг прокси.
+
+## Что здесь действует
+
+- **Свои теги помечены собственным атрибутом и при повторном применении переписываются.** Чужое
+  в голове документа не трогается: после оживления там остаются теги от отдачи сервером.
+- **Канонический адрес ведёт на локализованный путь**, а не на корень и не на адрес локали по
+  умолчанию.
+- **Языковые ссылки строятся по локалям, перевод которых готов**, плюс ссылка на локаль по
+  умолчанию. Полный список локалей для этого не годится: переводы содержимого заполняются
+  отдельно и готовы не всегда.
+- **Список альтернативных локалей не включает локаль самой страницы** — иначе она объявлена и
+  основной, и альтернативной сразу.
+- **Адрес в структурированных данных — канонический адрес самой страницы**, не корень.
+- **Перенаправление с прежнего адреса отдаётся с временем жизни и кэшируется прокси.** Ключ
+  кэша строится без строки запроса, поэтому запросы с ней идут мимо кэша.
+
+## Паттерны
+
+- `seo-page` — правка разметки страницы: теги, структурированные данные, новый маршрут, новая
+  страница в карте сайта.
+- `seo-verify` — проверка отданной разметки на прод-сборке.
+
+## Ловушки
+
+- **Тег, добавленный мимо общей службы, не помечен и потому не переписывается.** Он переживёт
+  переход между страницами и останется от чужой страницы.
+- **Новый маршрут без ветки под каждую локаль существует только в локали по умолчанию.**
+  Остальные адреса отдадут отказ и поисковику, и читателю.
+- **Новая страница не попадает в карту сайта сама** — карта строится из записей, а не из
+  маршрутов.
+- **Адрес режется по первому знаку вопроса и только им.** Простой разрез по всем вхождениям
+  теряет всё после второго, и перенаправление приходит на страницу без разметки источника —
+  источник обращения считается неверно.

package/assets/rules/shared-code.md

@@ -0,0 +1,45 @@
+---
+name: shared-code
+kind: rule
+law: shared-code
+description: Правило под закон «Общий код приложений». Брать, когда значение должно одинаково пониматься всеми приложениями — предел выборки, набор операторов условия, направление порядка, длина поля, форма запроса и ответа списка. Откуда берётся общее, что считается копией и что ловит проверка повторов. Готовый код — в паттерне shared-code-new. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Общий код — каким приёмом
+
+Правило под закон `{{lawsDir}}/shared-code.md`. Закон говорит, что общим быть обязано; здесь —
+каким приёмом это держится. Из какого пакета и какой либы что берётся — `implementation.md`
+рядом.
+
+## Когда берётся
+
+Значение, которое должны одинаково понимать разные приложения: число-настройка, набор значений,
+форма запроса и ответа списка, длина поля.
+
+## Что здесь действует
+
+- **Число-настройка лежит в общей либе и оттуда берётся всеми сторонами.** Умолчание доводом не
+  передаётся: пока довод есть, домен вправе назвать своё число — и называет, расходясь с
+  соседним на единицу, которую никто не заметит.
+- **Набор значений из общего пакета заново не объявляется.** Своё перечисление с теми же
+  членами считается копией, даже если имена разошлись.
+- **Значение из набора сверяется общей функцией, а промах разбирает вызывающий.** Сервер
+  отбивает запрос отказом, экран берёт умолчание: политика на непонятное значение у сторон
+  разная, и общей может быть только сверка.
+- **Общим делается лишь то, где политика одна.** Переводчик, у которого стороны читают
+  непонятное значение по-разному, общим не становится — он расходится молча.
+- **Перечисления полей порядка и отбора домена копией не считаются.** Они повторяют имена, по
+  которым сортирует сервер именно этого домена, и совпадение здесь случайное.
+
+## Паттерны
+
+- `shared-code-new` — как завести новое общее число, функцию или тип и не оставить копию.
+
+## Ловушки
+
+- **Помощник приведения типов для сверки с набором не годится.** Значение вне набора он пишет в
+  журнал и возвращает строкой, то есть глотает ровно тот случай, ради которого сверку и завели.
+- **Накопленные повторы лежат в списке исключений и отказом не считаются.** Гейт падает только
+  на новом; список исключений только сокращается.
+- **Проверка не ловит ту же логику, написанную заново под другим именем.** Совпадение она ищет
+  по тексту, а не по смыслу.

package/assets/rules/spec-driven.md

@@ -0,0 +1,89 @@
+---
+name: spec-driven
+kind: rule
+law: project-documentation
+description: Правило под закон «Документация проекта». Брать при правке спека домена, закона и любого скила. Три слоя — закон, правило, паттерн, — обязательные разделы, привязка утверждений к коду, связь сценариев с тестами. Готовый порядок действий — в паттернах spec-driven-domain и spec-driven-rule. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Документация проекта — каким приёмом
+
+Правило под закон `{{lawsDir}}/project-documentation.md`. Закон говорит, что должно быть верно
+про тексты; здесь — из каких слоёв они сложены и что сверяет машина. Где лежат спеки домена,
+чем они проверяются и какой у них шаблон — `implementation.md` рядом. Формулировки — правило
+`doc-style` под тем же законом.
+
+## Когда берётся
+
+Правка закона, правила, паттерна или спека домена. Заведение нового слоя документации.
+
+## Как сложены слои
+
+```
+ЗАКОН      {{lawsDir}}/<закон>.md
+           верен для любого приложения этого класса; о проекте не знает ничего:
+           ни путей, ни имён файлов, ни привязок
+
+  ├─ ПРАВИЛО    {{rulesDir}}/<правило>/SKILL.md      (kind: rule, law: <закон>)
+  │             каким приёмом закон исполняется; несколько правил на закон
+  │             {{rulesDir}}/<правило>/implementation.md — имена этого дерева и привязка к коду
+  │
+  │  └─ ПАТТЕРН  {{rulesDir}}/<правило>-<что>/SKILL.md  (kind: pattern, rule: <правило>)
+  │              готовый код и конкретные приёмы; минимум один на правило
+  │
+  └─ СПЕК ДОМЕНА  как работает домен; объявляет законы, которые применяет
+```
+
+Ссылки идут только снизу вверх: закон не ссылается ни на правило, ни на спек, ни на файл.
+
+## Что здесь действует
+
+- **Набор разделов спека задан заранее, и отсутствие раздела — отказ.** «Не применимо» —
+  законный ответ, отсутствие раздела — нет: сквозные требования вспоминаются постфактум именно
+  тогда, когда для них не заведено места.
+- **Каждое утверждение привязано к месту в коде, и связь сверяется в обе стороны.** Ключ связи
+  — сам текст утверждения, поэтому переформулировать его, забыв про привязку, нельзя.
+- **Привязка не ведёт в код, который никто не зовёт.** Символ, объявленный в своём файле и
+  больше нигде не встречающийся, местом исполнения не считается.
+- **Таблица обработчиков сверяется с объявлениями в обе стороны.** Иначе обработчик, который
+  домен обслуживает, но забыл описать, виден только в объявлении.
+- **Код отказа принимается, только если он в домене бросается.** Коды, выписанные по замыслу,
+  живут в документе годами, а на одном из путей обещанный отказ не бросает никто.
+- **Префикс сценариев в домене один.** Второй префикс означает, что домен описан дважды.
+- **У закона обязателен раздел статей, и кроме них он не держит ничего.** Истории правок и
+  доводов о выбранном когда-то варианте в законе нет: историю держит система контроля версий, а
+  довод с отвергнутой альтернативой — свойство работы, и место ему в «Ловушках» правила.
+- **Закон, назвавший файл проекта, — отказ.** Путям и привязкам место в правиле: иначе закон
+  нельзя ни прочитать без знания дерева, ни применить на другом приложении.
+- **Правило объявляет закон, под который написано.** Правило без закона — набор приёмов, из
+  которого не видно, что именно должно быть верно.
+- **Спек объявляет законы, которые применяет, и связь сверяется в обе стороны.** Закон,
+  названный в тексте спека, обязан стоять в его шапке: иначе по закону не узнать, какие домены
+  на нём стоят.
+
+## Паттерны
+
+- `spec-driven-domain` — заведение и правка спека домена, сценарии, привязка.
+- `spec-driven-rule` — заведение закона, правила и паттерна.
+
+## Ловушки
+
+- **Список шагов в спеке не заводить.** Шаги — артефакт сессии, им место в ветке или в описании
+  PR. Как только в директории появляются «шаги», спек снова становится планом и умирает после
+  слияния.
+- **Спек описывает установившееся, а не предстоящее.** Единственное место, где он говорит о
+  будущем, — отдельная директория предложенного; после выкатки её текст вливается в спек
+  домена, директория удаляется, идентификаторы сценариев не меняются.
+- **Семантику полей не сверяет ничто.** Проверка знает имена обработчиков, коды отказа и связь
+  сценариев с тестами; что означает пустое поле — не знает.
+- **Живость символа считается совпадением имени по дереву, а не вызовом.** Символу хватает
+  второго упоминания где угодно — в чужом поле с тем же именем, в атрибуте разметки. Место, где
+  правило исполняется на самом деле, подтверждается только чтением кода.
+- **Зелёная проверка не значит, что структура верна.** Проверка сверяет структуру с тем, чего
+  сама и ждёт: неверная раскладка, совпавшая с её ожиданием, проходит зелёной.
+- **Конфликт слияния в спеке разрешается сохранением обеих сторон, а не выбором одной.** Две
+  ветки дописывают в конец одних и тех же списков, и обе стороны верны: конфликт здесь не спор,
+  а две дописи в одно место. Номера сценариев при разрешении не пересчитываются — идентификатор
+  это ключ связи с тестами, и сдвиг номеров рвёт сверку у соседей, которых правка не касалась.
+  Порядок сохранённых сторон держится одинаковым во всех файлах спека, иначе правило, его
+  сценарий и его привязка перестают находиться друг по другу. После разрешения гоняется
+  проверка спеков: конфликт в тексте кода не задевает, и ни сборка, ни линтеры его не увидят.

package/assets/rules/styling-bem.md

@@ -0,0 +1,59 @@
+---
+name: styling-bem
+kind: rule
+law: frontend-application
+description: Правило под закон «Фронтовое приложение». Брать при правке любого файла стилей и шаблона компонента — токены оформления вместо сырых значений, класс директивой, общий слой раскладки, класс без правила. Готовый код — в паттернах styling-bem-layout и styling-bem-component. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Оформление — каким приёмом
+
+Правило под закон `{{lawsDir}}/frontend-application.md`. Закон говорит, что должно быть верно;
+здесь — каким приёмом это держится. Как названы токены, директивы классов и общий слой
+раскладки — `implementation.md` рядом. Раскладка файла компонента — `component-structure`,
+состояние — `angular-patterns`, окружение браузера — `platform-access`, слой обращения к
+серверу — `api-layer`. Все пять под одним законом.
+
+## Когда берётся
+
+Правка любого файла стилей и любого шаблона компонента. И раньше всего этого — момент, когда
+рука тянется написать шестнадцатеричный цвет или число на месте.
+
+## Что здесь действует
+
+- **Оформление берётся токеном, а не пишется значением на месте.** Составные значения — тени,
+  обводки — берутся готовым токеном целиком, а не собираются из частей: собранное из частей
+  расходится с оригиналом при первой правке шкалы.
+- **У каждого класса элемента есть своё правило стилей.** Класс без правила выглядит рабочим и
+  молча ничего не делает.
+- **Класс ставится директивой, а не строкой в атрибуте.** Имя блока элемент получает от
+  ближайшего предка, объявившего блок, и повторить этот разбор по тексту шаблона нечем.
+- **Раскладка объявлена в общем слое приложения, а не в стилях экрана.** У компонента экрана
+  файл стилей по умолчанию пустой.
+- **Предупреждение линтера стилей роняет прогон наравне с ошибкой.** Иначе запрет читается как
+  пожелание: нарушения лежат в дереве, а прогон возвращает успех и гейтом не является.
+
+## Паттерны
+
+- `styling-bem-layout` — экран на общем слое раскладки, блоки приложения.
+- `styling-bem-component` — стили компонента источника вида, хост, модификаторы.
+
+## Ловушки
+
+- **Директива элемента без предка, объявившего блок, роняет отрисовку во время работы** —
+  сборка и линтер при этом молчат.
+- **Директива блока на контейнере без своего узла класса не ставит вовсе:** такой узел это
+  комментарий, и имя блока он только объявляет потомкам. Класс блока экрана вешает хост.
+- **Выравнивание по центру в прокручиваемой ленте уводит первые элементы за нулевой скролл** —
+  доскроллить до них невозможно. В прокручиваемых лентах берётся безопасный вариант
+  выравнивания.
+- **Резерв под полосу прокрутки на корне сужает содержащий блок для закреплённых элементов.**
+  Попап, выровненный по правому краю, встаёт на ширину резерва левее своей кнопки.
+- **Изнутри компонента до соседнего хоста не дотянуться.** Разделитель между повторяющимися
+  хостами объявляется через отрицание первого, а не соседним селектором.
+- **Атрибут доступности визуального состояния не даёт.** Браузер стилизует собственное
+  состояние элемента, а атрибуты доступности — нет: к каждому такому атрибуту заводится своё
+  правило.
+- **Гарнитуру с корня элементы формы не наследуют** — браузер задаёт им свой шрифт.
+  Наследование включается глобально и не сбрасывается.
+- **Комментарии-выключатели линтера стилей не ставятся.** Селекторы объединяются вложенностью.
+- **При переносе стилей новых объявлений не появляется** — только перемещение существующих.

package/assets/rules/testing.md

@@ -0,0 +1,69 @@
+---
+name: testing
+kind: rule
+law: verifiability
+description: Правило под закон «Проверяемость». Брать при правке любого файла спеки и всего, что лежит в сквозных прогонах. Идентификатор сценария в заголовке теста, отметка непокрытого, вынос решения в чистую функцию, выключатели разрушающих спек. Готовый код — в паттернах testing-unit и testing-e2e. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Проверяемость — каким приёмом
+
+Правило под закон `{{lawsDir}}/verifiability.md`. Закон говорит, что считается подтверждением;
+здесь — каким приёмом это делается. Чем это названо в этом дереве, каким прогонщиком гоняется и
+где лежит — `implementation.md` рядом. Проверка работающего приложения глазами и замером —
+правило `browser-verification` под тем же законом.
+
+## Когда берётся
+
+Правка файла спеки, заведение теста, разбор упавшего прогона, закрытие сценария из спеки
+домена.
+
+## Что здесь действует
+
+- **Идентификатор сценария стоит в начале заголовка теста, через тире.** Один сценарий
+  проверяется несколькими тестами, один тест закрывает несколько сценариев; связь читается из
+  заголовка, а не из памяти писавшего.
+- **Сценарий без теста несёт отметку с причиной.** Пустая отметка не принимается, а отметка при
+  существующем тесте — отказ: она означает, что долг закрыли, а отметку не сняли.
+- **Тест, идущий не тем путём, что пользователь, помечается частичным покрытием.** В сводку он
+  попадает долгом, а не покрытием.
+- **Упоминание в тесте сценария, которого в спеках нет, роняет проверку.** Так ловится
+  переименованный или выкинутый сценарий: тесты при этом остаются зелёными.
+- **Решение выносится в чистую функцию и проверяется вызовом.** Компонент и сервис остаются
+  тонкой обёрткой и отдельно не проверяются, пока своего ветвления у них нет.
+- **Обработчик серверной стороны проверяется вызовом своего метода с рукописным двойником
+  хранилища.** Контейнер и маршрутизатор поднимать не надо: спека проверяет решение, а не
+  раскладку полей.
+- **Спека, необратимо меняющая данные стенда, выключена по умолчанию.** Адрес стенда уводится
+  одной переменной окружения, и без выключателя такая спека правила бы данные чужого стенда.
+- **Спеки, которым нужен прокси перед приложением, просыпаются вместе с адресом стенда.** Голый
+  сервер отдачи страниц их не проходит: перенаправления живут в конфиге прокси, а не в
+  приложении.
+- **Правило линтера, которое запрещает принятый здесь приём, выключают в конфиге, а не обходят
+  в каждом тесте.** Точечное отключение в файле остаётся для того, что запрещено по делу; рядом
+  со строкой отключения пишут причину.
+
+## Паттерны
+
+- `testing-unit` — тест на чистую функцию, на обработчик серверной стороны и разовый
+  тест-доказательство, который не коммитится.
+- `testing-e2e` — прогон сквозных тестов, стенд под настоящим прокси, выключатели.
+
+## Ловушки
+
+- **Зелёный прогон тестов не значит, что хоть один файл исполнялся.** Либа без своего конфига
+  прогонщика не запускает ничего. Либа с конфигом, но без единого файла спеки, проходит зелёной
+  из-за настройки «успех при отсутствии тестов», и на глаз эти два случая неотличимы: в обоих
+  прогон успешен. Перед правкой в незнакомой либе проверяется, есть ли в ней хоть один файл
+  спеки; если нет — первый заводится этой же правкой, а не откладывается: откладывать здесь не
+  с чего, долг уже накоплен.
+- **«Executable doesn't exist» — состояние машины, а не дефект правки.** Обычно установлен один
+  движок браузера, остальные падают всегда. Та же ошибка приходит после смены версии
+  прогонщика сквозных тестов: браузер ставится под конкретную версию, и после подъёма его надо
+  поставить заново. Выглядит это как регрессия обновления, а ею не является.
+- **Первому прогону сразу после установки браузера верить нельзя.** Падения, не повторяющиеся
+  ни при отдельном прогоне тех же тестов, ни при втором полном, — свойство первого прогона.
+  Такой прогон повторяют, а выводы делают по второму.
+- **Сквозные тесты без учётных данных в окружении пропускаются молча.** В отчёте они значатся
+  пропущенными, и прогон выглядит успешным.
+- **Поднятый сервер разработки проверкой не является.** Это шаг правила `browser-verification`,
+  а не тест.

package/assets/rules/translations.md

@@ -0,0 +1,52 @@
+---
+name: translations
+kind: rule
+law: locales
+description: Правило под закон «Локали и переводы». Брать при заведении любого видимого текста, правке словарей, префиксов локалей в адресе и перевода содержимого записи. Текст из словаря во всех локалях, пустой перевод как пропуск, производные переводы содержимого, начальная валюта локали. Готовый код — в паттерне translations-key. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Локали и переводы — каким приёмом
+
+Правило под закон `{{lawsDir}}/locales.md`. Закон говорит, что должно быть верно; здесь — каким
+приёмом это держится. Какие именно локали набраны, чем зовётся библиотека переводов и где лежат
+словари — `implementation.md` рядом.
+
+## Когда берётся
+
+Заведение любого видимого человеку текста, правка словаря, правка маршрутов с префиксом локали,
+перевод содержимого записи.
+
+## Что здесь действует
+
+- **Локаль по умолчанию отдаётся из корня, остальные — из-под префикса пути.**
+- **Видимый человеку текст берётся из словаря и заводится во всех локалях сразу.** Ключ,
+  потерянный в одной локали, читатель видит на кнопке как есть.
+- **Пустой перевод считается пропуском, а не переводом.** Запасной словарь подставляется только
+  на отсутствующий ключ, а пустую строку отдаёт как есть.
+- **Переводы содержимого производные: владелец пишет на своём языке, остальные локали
+  заполняются при сохранении.** Вкладок локалей в формах нет — ручная правка всё равно была бы
+  перезаписана.
+- **Отказ перевода сохранение не срывает.** Текст на локали ввода записывается, прежние
+  переводы остаются, и владелец видит предупреждение, а не сообщение об успехе.
+- **Локаль, для которой перевода не пришло, сохраняет прежнее значение.**
+- **Язык интерфейса выбирает владелец, и выбор живёт в его профиле.** Он же уходит в локаль
+  ввода при сохранении записи.
+- **У локали есть начальная валюта показа.** Дальше валюту выбирает читатель, и его выбор
+  сильнее умолчания локали.
+
+## Паттерны
+
+- `translations-key` — заведение ключа во всех локалях и подстановка в разметку.
+
+## Ловушки
+
+- **Полноту словарей держит не работающее приложение, а тест.** Он роняет прогон на
+  недостающем или пустом ключе; без него дыра видна только на экране.
+- **Наборы ключей сверяются внутри раздела**, а не по всему словарю сразу: словари разложены на
+  общий, публичную часть, письма и внутреннюю часть.
+- **Перевод содержимого идёт до записи, а не после.** Иначе страница оказывается наполовину
+  переведённой; кэш сбрасывается после записи и один раз.
+- **Без ключа доступа к переводчику сохранение проходит**, но переводы остаются прежними — и
+  единственный признак этого владелец видит предупреждением.
+- **Новый маршрут без ветки под каждую локаль существует только в локали по умолчанию.**
+  Остальные адреса отдадут отказ и поисковику, и читателю.

package/assets/rules/typescript-conventions.md

@@ -0,0 +1,46 @@
+---
+name: typescript-conventions
+kind: rule
+law: code-structure
+description: Правило под закон «Устройство кода». Брать при правке любого .ts, кроме тех, у которых есть своё правило, — род объявления в имени, модификаторы доступа, приватные поля, суффикс источника, запрет приведения в переводчике моделей. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Устройство кода — каким приёмом
+
+Правило под закон `{{lawsDir}}/code-structure.md`. Закон говорит, что должно быть верно про
+объявления; здесь — как это записывается. Какими правилами линтера это держится и где они
+лежат — `implementation.md` рядом.
+
+## Когда берётся
+
+Правка любого файла с кодом, у которого нет своего правила: функции, типа, перечисления,
+переводчика моделей, обработчика серверной стороны.
+
+## Что здесь действует
+
+- **Род объявления виден по префиксу имени, и это держат правила линтера.** У интерфейса, у
+  типа и у перечисления свои; проверяются все файлы с кодом, а не выборочно.
+- **Источник, за которым следят, назван суффиксом.** Пишущий источник и наблюдаемое, поднятое
+  из него, различаются в месте использования, а не переходом к объявлению.
+- **Тип берётся из того пакета, где объявлен.** Своя копия чужого типа расходится с оригиналом
+  молча, а компилируется из них только одна.
+- **Отметка об устаревании ставится вместе с обходом потребителей.** Пометка на типе красит
+  каждое место, где его ещё зовут: один `@deprecated` на файл даёт замечания во всех чужих
+  доменах разом, и правка перестаёт быть локальной.
+- **Приведение значения к типу в переводчике моделей не пишется.** Оно принимает любое значение
+  и компилируется — то есть снимает ровно ту проверку, ради которой переводчик и заведён.
+
+## Паттерны
+
+- `ts-procedure` — завести обработчик серверной стороны: класс, метка, право, регистрация.
+
+## Ловушки
+
+- **Неиспользуемый параметр убирается, а не переименовывается.** Подчёркивание перед именем
+  прячет замечание, но параметр остаётся в сигнатуре и продолжает обещать значение.
+- **Агрегат хранилища своим сгенерированным типом не аннотируется.** Сгенерированный тип шире,
+  чем результат выборки, и аннотация врёт — причём в сторону, которую компилятор не оспорит.
+- **Своё правило линтера включается вместе с переводом всех, кого оно ловит.** Включённое
+  поверх накопленного даёт красный прогон на файлах, которых правка не касалась.
+- **Приватное поле с решёткой видно только внутри класса.** Там, где к полю обращается шаблон
+  или обёртка каркаса, оно объявляется защищённым, а не приватным.

package/assets/templates/gate-map.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Карта «что правится — какое правило» этого дерева. Её читает хук гейта правил.
+#
+# Живёт в проекте, а не в пакете: имена каталогов, расширения и команды поставки у каждого
+# дерева свои. Пакет везёт механизм, проект — карту.
+#
+# Функция печатает ИМЯ ПРАВИЛА или молчит. Молчание — «правила на это нет», и гейт пропускает.
+#
+# Порядок веток решает: первое совпадение выигрывает, поэтому частное идёт раньше общего.
+# Файл спеки — не файл компонента, и обе ветки обязаны стоять до общей ветки расширения.
+
+skill_for() {
+    kind="$1"
+    target="$2"
+
+    case "$kind" in
+        edit)
+            case "$target" in
+                # Файлы самого агента правятся без правила: правило на них — это оно само.
+                */.claude/*)                        return 0 ;;
+                *.spec.ts)                          printf '%s' '<правило про тесты>' ;;
+                *.component.ts|*.component.html)    printf '%s' '<правило про компонент>' ;;
+                *.scss)                             printf '%s' '<правило про оформление>' ;;
+                */index.ts)                         printf '%s' '<правило про раскладку либ>' ;;
+                *.ts)                               printf '%s' '<правило про код>' ;;
+                *.md)                               printf '%s' '<правило про тексты>' ;;
+            esac
+            ;;
+        bash)
+            case "$target" in
+                *git\ commit*|*git\ push*|*gh\ pr\ create*) printf '%s' '<правило про поставку>' ;;
+            esac
+            ;;
+    esac
+
+    return 0
+}