@rt-tools/agent-kit 0.2.0 → 0.3.0

package/assets/patterns/ts-procedure.md

@@ -0,0 +1,66 @@
+---
+name: ts-procedure
+kind: pattern
+rule: typescript-conventions
+description: Паттерн правила typescript-conventions. Брать при заведении или правке обработчика серверной стороны — класс с полем метода контракта и методом обработки, зависимости конструктором, имя файла и класса, почему форма именно такая. Не брать для объявления доступа — это паттерн permissions-procedure.
+---
+
+# Обработчик серверной стороны
+
+Паттерн правила `typescript-conventions`. Что при этом должно быть верно — закон
+`{{lawsDir}}/code-structure.md`.
+
+## Когда брать
+
+- Заводится новый обработчик серверной стороны.
+- Правится тело существующего.
+- Домен переезжает на вертикальную нарезку.
+
+## Один обработчик — один класс
+
+Файл рядом со своим доменом, класс с публичным полем метода контракта и публичным методом
+обработки. Зависимости приходят конструктором: на серверной стороне внедрение конструкторное, и
+функции внедрения фронта там нет.
+
+```typescript
+@Injectable()
+@ConnectProcedure()
+@RequiresPermission('<ресурс>:<действие>')
+export class PingProcedure implements IConnectProcedure<typeof HealthService.method.ping> {
+    readonly #health: HealthCheckService;
+
+    public readonly method: typeof HealthService.method.ping = HealthService.method.ping;
+
+    constructor(health: HealthCheckService) {
+        this.#health = health;
+    }
+
+    public async handle(): Promise<{ status: EHealthStatus }> {
+        return { status: (await this.#health.check()).status };
+    }
+}
+```
+
+Объявление доступа обязательно, и оно ровно одно — паттерн `permissions-procedure`.
+
+## Почему форма такая
+
+Прежняя — регистрация с телами в замыканиях внутри вызова роутера — делала обработчик
+недостижимым для спеки: наружу торчал только метод регистрации. А регистрация сервиса целиком
+заглушает каждый непереданный метод ответом «не реализовано», поэтому один сервис контракта не
+мог обслуживаться двумя доменами.
+
+Класс решает и то, и другое: метод обработки зовётся спекой напрямую, а реестр кладёт
+обработчики поштучно.
+
+## Частые промахи
+
+- **Третий суффикс имени файла:** прежние имена уходят вместе с последним переехавшим доменом,
+  и новых таких файлов не заводится.
+- **Функция внедрения фронта в классе обработчика:** зависимости идут конструктором.
+- **Тело в замыкании внутри регистрации:** спека до него не дотянется.
+- **Обработчик без объявления доступа:** приложение не поднимется.
+- **Приведение к типу в переводе моделей:** на серверной стороне оно запрещено так же, как во
+  фронтовом переводчике.
+- **Свой тип у результата группирующей выборки:** он условный, собирается из аргументов вызова
+  и с выписанным руками не сходится.

package/assets/rules/angular-patterns.md

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

package/assets/rules/api-layer.md

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

package/assets/rules/browser-verification.md

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

package/assets/rules/component-structure.md

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

package/assets/rules/doc-style.md

@@ -0,0 +1,61 @@
+---
+name: doc-style
+kind: rule
+law: project-documentation
+description: Правило под закон «Документация проекта». Брать при правке любого документа, включая спеки, а также комментариев в коде, тел коммитов и описаний PR. Пути, которые существуют, пара «правка и её документ», словарь проекта, запрет упоминать чужие проекты. Готовые формулировки — в паттерне doc-style-write. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Тексты проекта — каким приёмом
+
+Правило под закон `{{lawsDir}}/project-documentation.md`. Закон говорит, что должно быть верно
+про тексты; здесь — каким приёмом это держится и что остаётся за автором. Где лежит словарь,
+чем проверяются пути и какие пары требует гейт — `implementation.md` рядом. Устройство спеков и
+слоёв документации — правило `spec-driven` под тем же законом.
+
+## Когда берётся
+
+Правка любого документа, комментария в коде, тела коммита, описания PR.
+
+## Что здесь действует
+
+- **Путь, названный в документе, существует.** Ссылка на переехавший файл читается как
+  действующее указание, и следующий читатель заводит снятое заново.
+- **Описание прошлого из проверки путей выведено целиком.** Архив по устройству называет файлы,
+  которых уже нет, и правкой это не лечится.
+- **Документ едет в том же коммите, что и правка, которую он описывает.** Обход — отметка с
+  причиной в теле коммита; пустая причина не принимается.
+- **Термин берётся из словаря проекта, а не придумывается на месте.** Слова, которого там нет,
+  у читателя нет тоже. Новое слово либо заводится в словаре вместе с правкой, либо заменяется
+  тем, что уже есть.
+- **Чужие проекты не упоминаются нигде** — ни имени репозитория, ни «портировано из», ни ссылок
+  на его файлы. Описывается то, что код делает здесь, в терминах этого проекта.
+
+## Паттерны
+
+- `doc-style-write` — как формулировать: примеры «так» и «не так», правила для комментариев.
+- `doc-style-sweep` — разбор документа, накопившего список работ, на действующее и закрытое.
+
+## Ловушки
+
+- **Оставшаяся работа не записывается в документ, а заводится задачей.** «Сделать потом» в
+  плане, README или спеке — второй список работ: он расходится с очередью задач молча, а
+  разбирать его потом дороже, чем завести задачу сразу. Документ держит только то, что задачей
+  не бывает: договорённости и решения, которые решено не править.
+- **Словарь действует и на разговор с владельцем, не только на файлы.** Слово, от которого в
+  дереве отказались, всплывает именно в отчёте о сделанном — и владелец читает ровно то слово,
+  которое просил не употреблять.
+- **Проход по словарю глазами слово не находит.** «Формулировки приведены к словарю» означает
+  ровно те строки, которые в тот момент читали. Снятое слово вычищается поиском по всему дереву,
+  а не вычиткой; ищутся сочетания, а не корень — совпадений по корню законных обычно больше,
+  чем нарушений.
+- **Снятое имя вычищается одним проходом по всему дереву:** правила, их зеркала, документы и
+  комментарии. Описание того, чего в коде уже нет, читается как действующее указание.
+- **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет внутри
+  одной ветки. Число, которое придётся пересчитывать при каждой правке, лучше не писать вовсе;
+  число, полученное разбором текста, сверяется на выборке руками — разбор, не знающий второй
+  формы записи, ошибается молча.
+- **Сделанность читается по дереву, а не по тексту, который о ней написан.** Это верно в обе
+  стороны: вычеркнутый пункт при несделанной работе и несделанным названная задача, закрытая
+  наполовину, встречаются одинаково часто. Пункт плана описывает день, когда его написали.
+- **Комментарий в файле — такое же утверждение, как строка в документе.** Выдуманное
+  обоснование живёт в коде годами и каждый раз читается как основание ничего не трогать.

package/assets/rules/git-workflow.md

@@ -0,0 +1,106 @@
+---
+name: git-workflow
+kind: rule
+law: delivery
+description: Правило под закон «Поставка». Брать на заведение задачи, ветки, коммит, пуш, создание PR, слияние, а также на правку схемы хранилища и её миграций. Задача как начало работы, колонка задачи как ход работы, соответствие задачи и ветки один к одному, формат коммита, обязательный состав PR, сторожевые хуки. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration и git-workflow-restart. Чем это названо здесь — в implementation.md рядом.
+---
+
+# Поставка — каким приёмом
+
+Правило под закон `{{lawsDir}}/delivery.md`. Закон говорит, что должно быть верно; здесь — каким
+приёмом это держится. Как названы главная ветка, борда, колонки, формат имени ветки и учётная
+запись машинной работы — `implementation.md` рядом.
+
+## Когда берётся
+
+Заведение задачи и ветки, коммит, пуш, открытие PR, слияние, правка схемы хранилища и её
+миграций, ручной перезапуск прода.
+
+## Что здесь действует
+
+- **Коммит в главную ветку отбивается гардом.** Гард ищет вызов коммита в любом месте команды и
+  смотрит текущую ветку на момент запуска, поэтому составная «создать ветку и сразу коммитить»
+  отклоняется целиком: ветки в момент разбора ещё нет.
+- **Ветка без номера задачи PR не открывает.** Локально такая ветка законна, но правка из неё —
+  это выкатка, за которой в очереди работ ничего не стоит.
+- **Номер ветки и номер в заголовке PR сверяются на месте, а состояние задачи — по борде.**
+  Формат читается из текста команды и работает без сети; существование задачи, её присутствие в
+  очереди, исполнитель и то, что она ещё открыта, — только когда есть чем спросить. Нет сети
+  или нет токена — второй ярус молча пропускается: проверка, падающая в самолёте, перестаёт
+  что-либо значить.
+- **Колонка задачи двигается тем же движением, что и работа.** Ветка заведена — задача
+  переставляется во взятые в работу, PR открыт — в разбор. Перевод идёт сразу за шагом, который
+  его вызвал: очередь работ читают между шагами, а не после них.
+- **Отставшая колонка находится сверкой очереди, а не глазами.** Сверка судит колонку по отчёту
+  в обе стороны: открытый PR при задаче не в разборе и разбор без открытого PR — оба
+  расхождения.
+- **Задачи, чинящиеся одной правкой, сливаются до слияния ветки.** Недостающее из поглощённой
+  дописывается в первую, а сама она уходит из очереди. После слияния ветки слить уже нельзя:
+  она въехала, и откатывается целиком.
+- **Слияние в главную ветку выкатывает прод.** Исключения по путям покрывают только документы,
+  поэтому переменные окружения, секреты и записи имён ставятся до слияния, а не после.
+- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
+  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
+  идёт с пустым значением, а пусто здесь означает разработку — со всеми отладочными
+  умолчаниями, которые она разрешает.
+- **Образы выкатываются по хешу коммита, а не по метке «последний».** Метка в реестре отстаёт
+  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
+  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит.
+- **Документ едет в том же коммите, что и правка.** Обход — отметка с причиной в теле коммита;
+  пустая причина не принимается.
+- **Заголовок коммита сверяется с форматом на месте.** Разобранный по типу и области заголовок
+  читается списком, а свободный текст — только целиком.
+- **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы стилей
+  вовсе, и правила оформления без второго прогона не проверяет ничто.
+
+## Паттерны
+
+- `git-workflow-commit` — ветка, коммит, пуш и PR от учётной записи машинной работы.
+- `git-workflow-merge` — влить главную ветку в ветку задачи и разрешить конфликт.
+- `git-workflow-migration` — файл миграции и прогон цепочки на одноразовом хранилище.
+- `git-workflow-restart` — ручной перезапуск прода без отката на прежний образ.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, нет: делится то, что придётся откатывать порознь. Сплошная правка,
+  разделённая «по объёму», кончается стиранием лишних задач, закрытием их PR и переносом
+  коммитов с конфликтами.
+- **Задача заводится одной командой, а не набором вызовов подряд.** Очередь работ к репозиторию
+  обычно не привязана, и задача попадает в неё только явным добавлением: переписанный руками
+  шаг оставляет её вне очереди, и заметить это нечем.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком.
+- **Колонка, приведённая в порядок задним числом, ничего не значила ровно тогда, когда очередь
+  читали.** Перевод стоит одной команды и делается на месте, а не собирается в уборку под
+  конец: очередь для того и ведётся, чтобы отвечать в любой момент.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не
+  по куску: обе копии сами по себе исправны, сборка и линтер зелёные.
+- **Конфликт при вливании главной ветки почти всегда лежит в текстах, а не в коде.** Соседние
+  ветки дописывают в конец одних и тех же списков; зелёная сборка после слияния про такой
+  конфликт не говорит ничего.
+- **PR без ревьювера, исполнителя и меток открывать нельзя.** Ревьювер не узнаёт, что его ждут,
+  а метки — единственное, по чему в очереди из полутора десятков PR видно род правки и её
+  область.
+- **Заголовок PR без номера задачи не сопоставить с очередью.** В списке PR тела не видно, а
+  строка о закрытии задачи живёт именно там. Название при этом идёт в сделанном: задача просит
+  исправить, PR отчитывается, что исправлено.
+- **На самом PR не гоняется ничто.** Выкатка запускается пушем в главную ветку, и выборочный
+  прогон по затронутому до PR не доходит: сборки, проверки текстов и браузер идут до
+  публикации.
+- **Субагентам работа с историей запрещена полностью, включая чтение состояния.** Отложенные
+  изменения, спрятанные субагентом, выглядят как потеря всей работы. Историю ведёт главный
+  агент.
+- **Подъём контейнера без явного тега образа подставляет «последний».** Приложение при этом
+  отвечает, и подмену видно только по пропавшим строкам нового кода в журнале.
+- **Команда разработчика для миграций на живом хранилище не запускается.** Любое расхождение
+  состояния она лечит предложением сбросить хранилище, а в нём лежат данные владельца.
+- **Переименованная миграция остаётся в хранилище под прежним именем.** Накат падает на «объект
+  уже существует» и лечится отметкой о применении, а не повторным накатом.
+- **Флаги инструмента миграций не те, что в примерах из сети.** На неизвестный флаг команда
+  печатает справку, а не строку ошибки, — промах виден только в ней. Какие флаги есть сейчас,
+  смотрят в её собственной справке, а не в этом тексте.

package/assets/rules/lib-layers.md

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

package/assets/rules/permissions.md

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