@rt-tools/agent-kit 0.5.3 → 0.7.0

package/assets/rules/git-workflow.gitlab.md

@@ -2,7 +2,7 @@
 name: git-workflow
 kind: rule
 law: delivery
-description: Правило под «Закон о поставке» для дерева на GitLab. Брать на заведение задачи, ветки, коммит, пуш, создание MR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав MR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration и git-workflow-restart.
+description: Правило под «Закон о поставке» для дерева на GitLab. Брать на заведение задачи, ветки, коммит, пуш, создание MR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав MR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration, git-workflow-restart, git-workflow-docker и git-workflow-secrets.
 ---
 
 # Поставка — как это устроено здесь
@@ -62,6 +62,11 @@ description: Правило под «Закон о поставке» для д
 - **Задачи, чинящиеся одной правкой, сливаются до слияния ветки.** Вторая стирается вместе с
   номером, а недостающее из неё дописывается в первую. После слияния слить уже нельзя: ветка
   въехала, и откатывается она целиком.
+- **Работа, которую одним заходом не закрыть, помечена в двух местах, и они сверяются.** Метка
+  на доске и строка о заходах с передачей в линии работ говорят одно и то же двум читателям:
+  исполнитель открывает карточку раньше, чем линию, а планирует по линии. Одна пометка без
+  другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
+  законно не делится: пометка объёма правом делить не становится.
 - **Слияние в главную ветку выкатывает прод.** Правила `only`/`rules` конвейера покрывают
   документы отдельно, поэтому переменные окружения, секреты и записи имён ставятся до слияния,
   а не после.
@@ -71,6 +76,25 @@ description: Правило под «Закон о поставке» для д
   умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
 - **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
   от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
+  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
+  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
+  через две выкатки, откатывается уже некуда.
+- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
+  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
+  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
+- **Правка конвейера прогоняется до слияния ручным запуском.** Конвейер запускается на любой
+  ветке, а задание выкатки прибито правилом к главной: прогон ради проверки доходит до сборок и
+  там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
+  а не файл конвейера, — верность самого файла читается только по списку конвейеров после
+  пуша, и синтаксис отдельно судит проверка `.gitlab-ci.yml` в проекте.
+- **Отчёт проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
+  образов идут на конвейере запроса слияния, выкатка — нет: её держит правило по главной ветке
+  у своего задания, а образ отчёта в реестр не уезжает.
+- **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
+  слиянием, но слияние — ещё не прод: отказавшая выкатка не трогает ни задачу, ни её список, и
+  заметить её неоткуда. Сверка спрашивает последний конвейер главной ветки и судит только
+  завершённый: идущий ещё может кончиться выкаткой.
 - **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
   лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
   ветки, начатой раньше, встаёт перед той, от которой зависит.
@@ -80,6 +104,25 @@ description: Правило под «Закон о поставке» для д
   заголовок читается списком, а свободный текст — только целиком.
 - **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы
   стилей вовсе, и правила оформления без второго прогона не проверяет ничто.
+- **Сборка входит в набор наравне с линтом и юнитами.** Линтер типов не читает, а юниты читают
+  только то, что импортировано тестом: ошибка типов в непокрытом коде доживает до сборки
+  образа, то есть до слияния. Четыре слияния подряд так и уехали в главную ветку, ломая
+  выкатку.
+- **Набор гейта пуша не бывает уже набора конвейера.** Гейт — обещание, что пуш не приедет
+  красным; набор, из которого выкинуты сборка и снимки, обещает то, чего не проверяет. Шаг
+  конвейера, которому в наборе гейта нет ни строки, ни объявленного исключения с причиной,
+  отбивает пуш, а не печатается рядом с ним: напечатанное предупреждение исполнитель читает как
+  разрешение. Дважды подряд правка, прошедшая гейт целиком, была отбита конвейером — и оба раза
+  зелёный гейт был прочитан как «локально всё зелено».
+- **После вливания главной ветки набор проверок пересматривается по тому, что ветка везёт
+  теперь.** Вливание меняет состав правки: проверять по тому, что правил автор, — значит
+  проверять половину, а отвечает ветка целиком. Ветка, не тронувшая ни строки показа, прогоняет
+  снимки витрин с того момента, как вливание принесло чужую правку оформления.
+- **Утверждение о главной ветке делается по удалённой ссылке, а не по локальной.** Локальная
+  протухает в ту минуту, когда её подтянули в последний раз, и молчит об этом: она не пуста и не
+  сломана, она описывает вчерашний день. Сравнение веток пишется от `origin/main` целиком —
+  смешав в одной команде удалённую ссылку для одной стороны и локальную для другой, промах
+  изнутри выглядит правильным.
 - **Слияние по кнопке «Merge when pipeline succeeds» не заменяет проверок до пуша.** Конвейер
   видит только то, что уже отправлено, а отправленная красная ветка занимает очередь работ и
   выглядит готовой к разбору.
@@ -121,6 +164,8 @@ description: Правило под «Закон о поставке» для д
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
 
 ## Ловушки
 
@@ -144,6 +189,21 @@ description: Правило под «Закон о поставке» для д
   записи, на следующий вызов это не переносится: MR открывают токеном учётной записи машинной
   работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
   смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+- **Невалидный файл конвейера виден отказом сразу после пуша, а не упавшим заданием.** Конвейер
+  на такой файл не заводится вовсе: в списке стоит запись об ошибке разбора, а внутри нет ни
+  задания, ни лога. Поэтому список конвейеров ветки смотрится тем же движением, что и пуш —
+  `glab ci list --branch <ветка>`, — а сам файл до пуша судит проверка `.gitlab-ci.yml` в
+  проекте.
+- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
+  конвейер.** Две стороны сходятся отдельно: `tags` у заданий и теги самого раннера. Пока
+  пересечения нет, раннер стоит `online` и не берёт ничего, а задания ждут общего раннера — по
+  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
+  не строку состояния.
+- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
 - **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
   разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
   входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,

package/assets/rules/lists.md

@@ -30,11 +30,24 @@ description: Правило под «Закон о списке записей»
 
 ## Как закон применяется здесь
 
+- **Страница собирается общим компонентом страницы списка, а не своей разметкой.** Заголовок,
+  панель действий, зона прокрутки и переключатель страниц одинаковы у всех списков, и
+  переписанные заново они расходятся молча.
+- **Механика экрана берётся из общей основы списочного экрана, а не пишется заново.** Экран
+  домена объявляет стор, ключ таблицы, поля сортировки и столбцы; выборка из адреса и в адрес,
+  страница, её размер, сортировка, тост отказа и переходы в панель уже там.
+- **Таблицу экран объявляет сам и кладёт внутрь шаблона.** Обернуть её нельзя: столбцы она
+  собирает собственным запросом по содержимому, и через посредника они до неё не доходят.
 - **Список собирается `<префикс>-table`, а не своей разметкой.** Скелетоны, пустое состояние,
   карточки на узком экране и настройка столбцов — входы таблицы; свой
   `@if (rows().length === 0)` означает, что экран собран мимо неё.
 - **Строки объявляются на `rowsTable.displayedColumns()`, а не на своём списке.** Столбец с
   меню таблица добавляет сама.
+- **Заголовок сортируемой колонки называет поле сервера, а не ключ колонки.** Колонка и поле
+  совпадают не всегда, и пока в разметке стоит ключ колонки, экран держит две карты перевода в
+  обе стороны.
+- **Сортируема та колонка, у чьей ячейки шапки стоит заголовок сортировки.** Отдельного
+  признака рядом со списком столбцов нет, и расходиться нечему.
 - **Клик по строке открывает запись, а меню — для действий над ней.** Вид нажимаемой строки
   даёт `clickable`, активацию мышью и с клавиатуры — `vmTableRow`; клик по кнопке внутри строки
   активацией не считается.

package/assets/rules/observability.md

@@ -0,0 +1,147 @@
+---
+name: observability
+kind: rule
+law: observability
+description: Правило под «Закон о наблюдаемости». Брать при правке логгера, контекста запроса, домена отказов и домена оповещений, при заведении новой строки лога и когда решается, что владелец узнает об отказе. Называет уровни, номер обращения, вычистку секретов, сводку старта и то, что уходит наружу при отказе. Готовый код — в паттерне observability-record.
+---
+
+# Наблюдаемость — как это устроено здесь
+
+Правило под закон `docs/constitution/observability.md`. Закон говорит, что владелец должен
+знать о работе приложения; здесь — как это названо в этом дереве, где лежит и чего пока нет.
+
+## Как это называется здесь
+
+| В законе                                                   | Здесь                                                                                                                              |
+| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| то, что приложение о себе пишет                            | логи приложения: одна строка на каждый вызов логгера, в машинном виде                                                              |
+| ступень важности                                           | уровень: от подробностей разбора до отказа, поднявшего процесс                                                                     |
+| номер обращения                                            | идентификатор запроса, он же заголовок ответа                                                                                      |
+| признак, по которому находятся все отказы одного обращения | тот же номер обращения — он стоит в каждой строке лога                                                                             |
+| подробности отказа                                         | разобранная причина: класс, текст, код протокола, код и подробности от хранилища, срезанный стек                                   |
+| общий текст ошибки наружу                                  | внутренняя ошибка без подробностей                                                                                                 |
+| вычистка секретов                                          | замена значений по имени поля                                                                                                      |
+| отказ в хранилище                                          | то, что домен отказов сохранил: группа отказов и её вхождения                                                                      |
+| то, с чем приложение поднялось                             | сводка старта: одна строка лога с версией, портом, адресом хранилища и списками возможностей — включённых, выключенных и сломанных |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Номер обращения заводится один раз на запрос и стоит в каждой строке лога о нём.** По
+  времени строки одного обращения не отобрать: обращений бывает десяток в секунду.
+- **Номер обращения уходит вызывающему заголовком ответа и в подробностях отказа.** Он же стоит
+  в логах, поэтому названный человеком номер ищется прямым отбором. Заголовок при этом открыт
+  странице чужого домена: без явного разрешения браузер его не отдаёт.
+- **Номер, пришедший снаружи, чистится и укорачивается, а пустой заводится заново.** Значение
+  из заголовка приходит от кого угодно, а попадает в отбор по хранилищу.
+- **Наружу уходит код и общий текст ошибки, подробности остаются в логах.** Иначе гость на
+  сломанной выкатке прочитает имя колонки и устройство хранилища.
+- **Отказ по вводу и правам пишется отдельно от поломки и без стека.** Это сработавшая
+  проверка. На одном уровне с поломками она забивает тревогу опечатками гостей.
+- **Причина отказа разбирается в одном месте.** Иначе одна и та же ошибка приходит в логи
+  тремя разными формами.
+- **Поля строки лога вычищаются всегда, а не по решению того, кто пишет.** Решать на каждом
+  вызове, есть ли в полях секрет, — значит однажды ошибиться.
+- **Приложение при старте пишет, с чем поднялось.** Половина возможностей включается наличием
+  переменной окружения и без неё молча выключена. Иначе на вопрос «почему там не работает то,
+  что работает локально» отвечают чтением настроек прода по ssh.
+- **В сводке старта стоят имена возможностей и их состояние, но не значения переменных.**
+  Состояния разложены тремя списками, а не картой «имя → состояние»: вычистка работает по
+  имени ключа, и карта приехала бы в лог вычищенной ровно там, где состояние и нужно.
+- **Возможность, включаемая парой ключей, знает третье состояние.** Половины пары лежат по
+  разные стороны поставки, и заполнить можно ровно одну; тогда возможность не выключена и не
+  включена, а сломана — списком из двух состояний этот случай назвать нечем, и он читается как
+  включённый.
+- **Порог уровня решает, появится ли строка лога в выводе, но не в хранилище отказов.** Порог
+  ставится ради объёма вывода, и при высоком пороге отобранные строки нижнего уровня пропали бы
+  из хранилища молча.
+- **Отобранная строка лога сохраняется в хранилище отказом.** Отбирается уровень отказа и всё,
+  что выше, и строки уровнем ниже — по списку имён, объявленному в коде.
+- **Логгер отдаёт отказ приёмнику, а хранилища не видит.** Интерфейс приёмника объявлен рядом с
+  логгером, исполняет его домен отказов, и ставится он извне при старте.
+- **Строки лога клиента хранилища, домена отказов и домена оповещений в приёмник не идут.**
+  Отсекается источник, а не момент записи: медленная вставка в таблицу отказов сама порождает
+  строку лога клиента хранилища, и признаком «я внутри записи» её не поймать. Домен оповещений
+  отсечён по той же причине: сбой оповещения стал бы новым отказом, тот — новым оповещением.
+- **Обращение к чужой службе идёт с явным пределом ожидания.** Без него молчащая — не
+  отказавшая — служба держит соединение до умолчания среды, а это минуты: отказа нет,
+  записывать нечего, и владельцу такое молчание неотличимо от исправной работы. Предел
+  называется числом рядом с клиентом, потому что цена ожидания у каждой службы своя.
+- **Отправка наружу заводит свою строку до обращения, а исход дописывается в неё после.**
+  Строку заводит тот, кто видит хранилище, а не тот, кто отправляет: клиент внешней службы
+  хранилища не видит вовсе. Она же служит замком — второе обращение по той же записи не
+  уходит, — и по незакрытой строке видно разницу между «идёт прямо сейчас» и «упало посреди
+  отправки».
+- **Запись отказа не задерживает ответ и не роняет запрос.** Между логгером и хранилищем стоит
+  очередь с пределом; переполненная очередь отбрасывает новый отказ и считает отброшенное.
+- **Контекст запроса снимается в момент вызова логгера, а не в момент записи.** К моменту
+  записи хранилище исполнения уже отдано следующему запросу.
+- **Записанное владелец читает своим разделом, закрытым отдельным правом.** Группы своего
+  владения, а под группой — её вхождения с причиной, полями строки лога и телами.
+- **Хранилище не растёт без предела: раз в сутки лишнее и старое удаляются.** Удаляются
+  вхождения: сперва лишние за пределом, потом старые за сроком. Группа, у которой после этого
+  не осталось ни одного вхождения, уходит третьим шагом — и только если она старше часа: между
+  её заведением и первым вхождением проходит отдельный запрос.
+- **Предел хранилища назван числом строк, а не байтами.** Удаление физический размер таблицы не
+  уменьшает, и условие «размер под пределом» не стало бы верным никогда.
+- **О новом отказе владелец узнаёт сам — строкой журнала событий и письмом.** Обе дороги
+  открывает один порог: новая группа или группа, молчавшая дольше суток.
+- **В письме нет ничего, что закрыто правом на экран отказов.** Оно уходит на адрес, который
+  правами не закрыт ничем, и подробности в нём обошли бы право почтой.
+- **Частоту отказов владелец читает кривой над лентой: столбик — ведёрко выбранного периода.**
+  Счётчик группы говорит, сколько раз она случилась, но не когда: по нему не отличить поломку,
+  которая идёт потоком сейчас, от набравшейся за месяц.
+- **Тревогу поднимает рост поломок, а не всех отказов.** Отклонённый вызов — сработавшая
+  проверка, и таких девять из десяти: на их фоне рост поломок не заметен вовсе.
+- **Всплеск считается по последнему закрытому ведёрку, текущее правилу не отдаётся.** Оно ещё
+  набирается, и в начале каждого периода сравнение с ним показывало бы падение частоты.
+- **Частоту разбирает такт расписания, а не запрос экрана.** Кривая считает тревогу при каждом
+  ответе, но экран владелец может и не открыть, а узнать о всплеске должен без этого.
+- **О всплеске владелец узнаёт строкой журнала и письмом; повтор письма держит
+  предохранитель.** Одно происшествие занимает в ленте одну строку, а письмо о затяжной
+  поломке нужно и назавтра.
+
+## Чего из закона здесь нет
+
+Отказ, случившийся до подъёма приложения, записать некуда: хранилища в этот момент ещё нет.
+Такие остаются только в выводе контейнера. Туда же уходит отказ самого хранилища: его строки
+лога отобраны из отказов целиком, иначе поломка хранилища порождает поток, который сам себя
+разгоняет.
+
+Список отобранных имён нижнего уровня не сверяется ни с чем. Новое место, которому надо в
+хранилище, дописывает себя в него руками, а забытое молча остаётся только в выводе.
+
+Правильность выбора уровня не проверяет ничто. Новое место само решает, какой уровень взять, и
+ошибку видно только при чтении кода.
+
+Полнота сводки старта не сверяется ничем. Имена возможностей перечислены руками, а переменную
+окружения читают десятки файлов по всем доменам: новая возможность, забывшая дописать себя в
+сводку, молча не попадёт ни в один из трёх списков — и на проде будет выглядеть не выключенной,
+а несуществующей. Само чтение переменной окружения поэтому и требует этого правила вторым
+слоем: гард видит обращение к окружению в тексте правки, но не то, дописали себя в сводку или
+нет.
+
+## Паттерны
+
+- `observability-record` — как завести новую строку лога.
+
+## Ловушки
+
+- **Контекст запроса живёт в хранилище исполнения и в отложенную работу не переезжает.**
+  Отложенная запись прочитает контекст того обращения, которое заняло место исходного. Снимать
+  контекст надо в момент вызова логгера.
+- **Логгер ставится на всё приложение, поэтому строки каркаса идут тем же путём, что и свои.**
+  Всё, что каркас пишет о себе, попадает в тот же вывод и в тот же отбор.
+- **Отказ потока приходит после того, как ответ начался.** Управление возвращается, когда отдан
+  только заголовок. Без обёртки такой отказ не попадёт в логи вовсе.
+- **Сериализация строки лога не должна бросать исключение.** Циклическая ссылка в полях иначе
+  уронит запрос, ради лога которого её и складывали.
+- **Ключ, в который заворачивают чужое тело для вычистки, выбирается по правилам вычистки.**
+  Она работает по имени ключа, и голое значение мимо неё проходит вовсе, — но ключ, который сам
+  числится свободным текстом, увозит тело в хранилище отметкой о вычистке целиком. Новая
+  обёртка сверяется со списками ключей до того, как её так назвали.

package/assets/rules/permissions.md

@@ -36,6 +36,29 @@ description: Правило под «Закон о доступе». Брать
   Последний отдаёт вошедшему больше, чем гостю, — так владелец видит скрытые объекты в общем
   списке.
 - **Права пользователя — это права пресета, поверх которых применены его оверрайды.**
+- **У человека одна роль во владении, и держит это хранилище.** Две принадлежности в одном
+  владении пришлось бы складывать, а результат сложения запретов и разрешений по двум строкам
+  не прочитать. Права разных владений не складываются вовсе: они записаны у принадлежности, а
+  не у учётной записи.
+- **Право, о котором роль ничего не говорит, считается неданным.** Значение, которое не булево,
+  отбрасывается при сложении: отсутствующее право и прямо отобранное означают одно и то же, и
+  «непусто» правом не считается.
+- **Права вошедшего читаются при каждом вызове, а не берутся из выданного входа.** Выданный
+  вход говорит только о том, кто пришёл: подписанное однажды живёт часами и правку прав не
+  переживает, поэтому отобранное право открывало бы раздел до конца дня.
+- **Учётная запись, которой больше нет, вызовов, требующих входа, не открывает.** Тем же
+  чтением отбивается и человек, потерявший принадлежность в своём владении: работать ему не в
+  чем.
+- **Счётчик и рекламные сигналы включает ответ гостя, а не наличие ключа в настройках.**
+  Решений два, и хранятся они парой: «разрешил счёт посещений, но не рекламу» — законное
+  состояние, а третьим значением перечисления его пришлось бы заводить заново на каждое новое
+  разрешение. Всё, что не пара булевых значений, читается как неотвеченный вопрос, то есть как
+  отказ: хранилище принимает что угодно, а решать по испорченной записи нельзя. Своя
+  статистика к согласию не привязана — она не уходит наружу.
+- **Публичная процедура, заводящая запись, закрыта ещё и ограничителем частоты.** Право её не
+  сторожит, и без предела скорость роста таблицы задаёт отправитель, а не владелец. Считается
+  по ключу клиента, и ключ у всех таких процедур общий: второй ответ на вопрос «кто это»
+  разошёлся бы с первым. Публичная процедура, которая только читает, ограничителя не требует.
 - **Запрос без входа отбивается как неаутентифицированный, а вход без права — как отказ в
   доступе.** Это разные ответы: первый лечится входом, второй — нет.
 - **Право проверяется перехватчиком до тела процедуры.** Обработчик не решает, пускать ли

package/assets/rules/reuse-first.md

@@ -27,6 +27,10 @@ description: Правило под «Закон о единообразии пр
 
 ## Как закон применяется здесь
 
+- **Источник вида выбирается по приложению, а не по привычке.** У каждого приложения дерева
+  своя опора: у публичного сайта — его дизайн-система, у остальных — кит. Перепутанный источник
+  приносит на экран форму, которой в этом приложении больше нигде нет. Какое приложение на что
+  опирается, названо в именах дерева.
 - **Работа начинается с чтения готового, а не с чистого файла.** Сначала находится опора —
   компонент кита, базовый класс, образец в соседнем домене, — потом пишется своё поверх неё.
 - **Свой примитив и своя основа заводятся только с явного одобрения владельца.** Спрашивается
@@ -76,6 +80,11 @@ description: Правило под «Закон о единообразии пр
 
 ## Ловушки
 
+- **Образец ищется по именам кита, а не по тому, на чём кит написан.** Поиск по именам
+  библиотеки, поверх которой кит собран, не находит ни одного файла: наложение, портал и окно
+  закрыты китом и зовутся его именами. Обратное тоже бывает: библиотека стоит прямой
+  зависимостью, и то, чего кит не закрывает, зовётся в дереве её собственным именем. Прежде чем
+  решать, что имени в дереве нет, его ищут — переделок из-за этого выходит по две на приём.
 - Перенос переизобретением не считается: строку, которая уже лежит в файле, гард из
   проверяемого текста вычёркивает, а сверка идёт без отступов — при переезде блок меняет
   отступ, оставаясь тем же кодом.

package/assets/rules/seo.md

@@ -2,7 +2,7 @@
 name: seo
 kind: rule
 law: search-visibility
-description: Правило под «Закон о видимости в поиске». Брать при любой правке, доходящей до разметки публичного сайта — шаблоны страниц, meta/title/description, JSON-LD, canonical, hreflang, маршруты сайта, sitemap, robots, nginx. Называет восемь локалей, где что лежит и чего у нас нет. Готовый код — в паттернах seo-page и seo-verify.
+description: Правило под «Закон о видимости в поиске». Брать при любой правке, доходящей до разметки публичного сайта — шаблоны страниц, meta/title/description, JSON-LD, canonical, hreflang, маршруты сайта, sitemap, robots, nginx. Называет локали перевода, где что лежит и чего у нас нет. Готовый код — в паттернах seo-page и seo-verify.
 ---
 
 # Видимость в поиске — как это устроено здесь
@@ -12,14 +12,14 @@ description: Правило под «Закон о видимости в пои
 
 ## Как это называется здесь
 
-| В законе                     | Здесь                                                                        |
-| ---------------------------- | ---------------------------------------------------------------------------- |
-| язык страницы                | локаль; их восемь — `en`, `ru`, `de`, `zh-Hans`, `zh-Hant`, `ko`, `th`, `hi` |
-| язык по умолчанию            | `DEFAULT_LOCALE`, то есть `en`; отдаётся из корня, без префикса в адресе     |
-| язык, перевод которого готов | `readyLocales` — поле объекта, а не список локалей сайта                     |
-| канонический адрес           | `${SITE_ORIGIN}${propertyPath(slug, locale)}`                                |
-| структурированные данные     | JSON-LD типа `LodgingBusiness`                                               |
-| прежний адрес страницы       | прежний slug объекта                                                         |
+| В законе                     | Здесь                                                                    |
+| ---------------------------- | ------------------------------------------------------------------------ |
+| язык страницы                | локаль перевода; их набор — в `implementation.md` рядом                  |
+| язык по умолчанию            | `DEFAULT_LOCALE`, то есть `en`; отдаётся из корня, без префикса в адресе |
+| язык, перевод которого готов | `readyLocales` — поле объекта, а не список локалей сайта                 |
+| канонический адрес           | `${SITE_ORIGIN}${propertyPath(slug, locale)}`                            |
+| структурированные данные     | JSON-LD типа `LodgingBusiness`                                           |
+| прежний адрес страницы       | прежний slug объекта                                                     |
 
 Локаль по умолчанию отдаётся из корня, остальные — с префиксом `/<код>/`. Префикс — часть
 маршрута, а не часть сборки: `<base href>` в разметке всегда `/`.
@@ -46,6 +46,54 @@ description: Правило под «Закон о видимости в пои
 - **Перенаправление с прежнего адреса отдаётся с `Cache-Control: max-age`** и покрыто
   `proxy_cache_valid 200 301`. Ключ кэша строится без `$args`, поэтому запросы со строкой
   запроса идут мимо кэша (`proxy_cache_bypass` / `proxy_no_cache $is_args`).
+- **Страница отдаёт блоки JSON-LD каждый своим тегом**, а не одним графом: отказ одного не
+  уносит остальные, и в отданной разметке видно, какой из них собрался.
+- **Цена уходит и предложением, и диапазоном** — суммой в валюте хранения и с единицей своего
+  периода. Цена по датам, скидки и пересчёт в валюту гостя в разметку не идут.
+- **Сводная оценка появляется от первого отзыва** и считается из оценок самих отзывов. Ноль
+  отзывов — поля нет вовсе: ни нуля, ни пустой строки.
+- **Блок вопросов собирается из вопросов записи**, а ноль вопросов блока не даёт.
+- **Крошки ведут от корня локали к странице записи** адресами той же локали, что и открытая
+  страница. Без названия сайта крошки не выпускаются вовсе.
+- **Сохранение записи уведомляет поисковика об изменении её адресов.** В уведомление уходят
+  страницы записи на готовых локалях по нынешнему и прежним адресам; корни локалей и карта
+  сайта — нет. Отказ приёмника сохранение не отменяет и возвращается владельцу исходом.
+- **Приёмников несколько, и каждый получает свой запрос.** Опрашиваются они одновременно, а
+  потолок ожидания считается на приёмник: последовательный обход сложил бы все потолки в одно
+  ожидание владельца. Переменная окружения перекрывает адреса всех приёмников разом — этим
+  отправку и проверяют локальным приёмником.
+- **Исход возвращается перечислением по приёмнику, а владельцу показывается списком.** Приёмник
+  в нём назван словом, а не адресом. Строка отвечает за приём запроса, а не за осведомлённость
+  поисковика: раздаёт полученное любой приёмник, поэтому отказ одного адреса не значит, что его
+  поисковик не узнал. Подписью объявляется только полный отказ.
+- **Удаление записи уведомляет поисковика теми же адресами.** Отдельного «страница исчезла»
+  протокол не знает: площадка приходит по адресу и видит ответ сайта сама. Адреса собираются до
+  удаления строки — каскад унесёт прежние вместе с записью, — а исход наружу не выходит:
+  страницы уже нет, и читать подпись некому. Снятие с публикации идёт через сохранение и
+  уведомляет тем же путём.
+- **Переименование адреса и снятие прежнего адреса тоже уведомляют поисковика.**
+  Переименование — всеми адресами записи, снятие — одним снятым; готовые локали у снятого
+  считаются по текстам записи, которой он принадлежал, и ради них выборка снятия отдаёт не
+  только адрес. Исход наружу не выходит ни там, ни там: владелец на странице адресов
+  спрашивает про адрес, а не про уведомление.
+- **Правка настроек владельца уведомляет поисковика адресами всех действующих записей.**
+  Видимой гостю считается та же правка, которой сбрасывается кэш, — а правка невидимого поля
+  уведомления не шлёт. Уходят живые адреса, без прежних, и готовые локали считаются по каждой
+  записи отдельно; отправка идёт на владеющую сущность — записи разных сущностей в одну не
+  попадают. Работа идёт в фоне за сохранением настроек, поэтому исход остаётся в логах:
+  показать его владельцу негде.
+- **Каждая отправка оставляет запись, и заводится она до обращения к приёмникам.** Повод,
+  записи, объявленные адреса и исход по каждому приёмнику ложатся рядом; пустой исход означает
+  «отправка идёт», а спустя несколько минут — что процесс упал посреди опроса. Пишут её все
+  места, откуда уведомление уходит. Отказ записи отправку не отменяет.
+- **Непрошедшие запросы владелец повторяет нажатием, и повтор заводит новую запись.**
+  Повторяется последняя отправка записи — у ранней адреса могли устареть, — и запрос уходит
+  только тем приёмникам, чей исход не «принял»; у оборванной записи это все её приёмники. Повод
+  у новой записи свой, а право строже, чем у чтения: повтор объявляет адреса поисковику.
+  Автоповтора по расписанию нет.
+- **Записи отправок держит ночная чистка: сперва предел, потом срок.** Тот же порядок, что у
+  ленты происшествий: срок, снятый первым, оставил бы предел меряться по уже почищенной
+  таблице.
 
 ## Чего из закона здесь нет
 

package/assets/rules/shared-code.md

@@ -39,6 +39,12 @@ description: Правило под «Закон об общем коде при
 - **Общим стал только маппер страницы.** У сторон разная политика на непонятное значение, и
   общим может быть лишь то, где она одна: номер меньше единицы обе стороны читают как первую
   страницу.
+- **Общая выборка держит форму запроса, а не набор условий.** Имена полей отбора объявляет сам
+  домен списком разрешённых, а в запрос к хранилищу их переводит его же выборка. Поэтому
+  условие вправе лечь на связанные строки, а не только на колонки самой записи, и отбор по
+  набору идентификаторов ей не запрещён: признак связанной записи — такое же поле набора, как
+  повод и объект. Общими здесь остаются разбор страницы, порядка и поиска, а не сам список
+  полей.
 - **Перечисления полей порядка и отбора домена копией не считаются.** `EActivitySortProperty`
   и подобные повторяют имена, по которым сортирует сервер именно этого домена.
 - **Строковая настройка и таблица соответствий сверяются по значению, а не по имени.** Имя

package/assets/rules/spec-driven.md

@@ -109,6 +109,15 @@ description: Правило под «Закон о документации пр
   про дерево, где того гарда не разложили; поправить это дерево не может ничем, если у ресурса
   нет надстройки. Требование ресурса к ресурсу при этом объявляется строкой в шапке, а не
   выводится из такой фразы.
+- **Паттерн находится по полю `rule:`, а не по приставке имени.** Приставку имени несут не все
+  паттерны, и поиск по имени правила таких не видит: сверка ищет их полем, человек — разделом
+  «Паттерны» самого правила. Счёт паттернов, собранный приставками, выходит меньше настоящего, а
+  число потом уезжает в деление работы.
+- **Якорь сверяется по сырому тексту файла, и комментарий засчитывается наравне с кодом.**
+  Существование символа проверка ищет словом по всему файлу, не вычищая комментарии, а живость
+  считает только у объявленного в коде. Имя, стоящее в одном лишь пояснении, проходит мимо обеих
+  сторон: якорем утверждения оказывается слово из комментария, тогда как объявление рядом
+  называется иначе.
 
 ## Чего из закона здесь нет
 

package/assets/rules/styling-bem.md

@@ -16,7 +16,7 @@ description: Правило под «Закон о фронтовом прило
 
 | В законе                        | Здесь                                                                                                                                        |
 | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| общий набор значений оформления | шкалы кита `--rt-*`; своё поверх них — `--vm-*` в `styles.scss` приложения                                                                   |
+| общий набор значений оформления | шкалы кита `--rt-*`; своё поверх них — `--<префикс>-*` в `styles.scss` приложения                                                            |
 | класс в разметке                | директивы `rtBlock` и `rtElem` из `@rt-tools`, а не строка в атрибуте                                                                        |
 | правило стилей                  | объявление `&__<элемент>` в `.scss` — своём или в общем слое приложения                                                                      |
 | общий слой раскладки            | `apps/<app>/src/styles/`: `<префикс>-page`, `<префикс>-form`, `<префикс>-panel`, `<префикс>-window` у админки, `<префикс>-site-page` у сайта |
@@ -38,6 +38,19 @@ description: Правило под «Закон о фронтовом прило
   инъекцией от ближайшего предка с `rtBlock`, и повторить этот разбор по тексту шаблона нечем.
 - **Раскладка объявлена в общем слое приложения, а не в стилях экрана.** У компонента экрана
   вне кита файл стилей по умолчанию пустой.
+- **Шторку и окно открывает служба кита, а не номер слоя.** Числа шкалы сравниваются только
+  между соседями по разметке; служба выносит разметку наружу, к `<body>`, и сравнивать её
+  становится не с чем.
+- **Номер слоя берётся из шкалы, а не пишется числом в файле компонента.** Шкала — единственное
+  место, где слои видно рядом: написанное на месте число в неё не попадает, и следующий узел
+  занимает тот же номер, ничего об этом не узнав.
+- **Размер элемента управления выбирается по признаку указателя, а не по ширине экрана.**
+  Планшет в ландшафте шире порога узкого вьюпорта, а нажимают по нему пальцем: `pointer: coarse`
+  отвечает про способ нажатия, ширина — про место под раскладку. Ступени берутся у кита, а не
+  назначаются пикселями.
+- **Файл стилей не длиннее 500 строк.** Предел общий с кодом и текстами, но stylelint длину не
+  судит вовсе — держит его проверка дерева. Выросший файл экрана делится по блокам, а общая
+  раскладка уходит в свой слой.
 - **Предупреждение stylelint роняет прогон наравне с ошибкой.** `!important` объявлен
   предупреждением, а прогон идёт с `--max-warnings 0`: иначе запрет читается как пожелание —
   два таких предупреждения лежали в дереве, а `npm run stylelint` возвращал ноль и гейтом не был.
@@ -52,10 +65,30 @@ description: Правило под «Закон о фронтовом прило
 
 - `styling-bem-layout` — экран на общем слое раскладки, блоки приложения.
 - `styling-bem-component` — стили компонента кита, `:host`, модификаторы, язык оформления сайта.
+- `styling-bem-sheet` — шторка и окно поверх страницы: чем открываются, подложка, замер.
 
 ## Ловушки
 
 - **`rtElem` без предка с `rtBlock` роняет отрисовку в рантайме** — сборка и линт молчат.
+- **Спроецированный узел блока-предка не имеет.** `rtElem` берёт имя блока инъекцией от
+  ближайшего предка **по месту объявления шаблона**, а не по месту вставки: элемент, который
+  экран объявляет у себя и отдаёт в проекцию чужого компонента, ищет `rtBlock` в своём шаблоне
+  и не находит. Отрисовка падает в рантайме, сборка и линт зелёные. Класс на такой узел
+  вешается правилом по селектору кита в общем слое раскладки, а не директивой.
+- **Элемент с `backdrop-filter` или своим `z-index` замыкает потомков в свой слой.** Липкая
+  шапка с размытием — самый частый случай: номер слоя у того, что лежит внутри неё,
+  сравнивается не с соседями по странице, а только с соседями внутри шапки, и нижняя панель
+  накрывает открытую шторку вместе с её кнопкой. Проверяется это `elementFromPoint` в центре
+  кнопки: сборка, линт и скриншот показывают тут целую страницу.
+- **До узла, вынесенного к `<body>`, стили компонента не достают.** Превью и заглушку переноса
+  кладёт туда библиотека, а правила компонента заскоуплены атрибутом: файл выглядит рабочим и
+  не красит ничего. Такие правила объявляются в общем слое приложения. Ни сборка, ни линт, ни
+  проверка «класс без правила» этого не видят: класса такого в шаблоне нет вовсе, и пролежать
+  это может несколько задач подряд.
+- **Имя токена не сверяется ничем.** Ссылка на несуществующий токен собирается, проходит
+  stylelint и проверку класса без правила, а свойство молча берёт наследованное значение:
+  правило выглядит написанным и не красит ничего. Ловится это только замером в браузере, а
+  имена берутся из объявлений кита, а не по догадке о том, как токен должен был бы называться.
 - **`rtBlock` на `<ng-container>` класса не ставит вовсе:** узел это комментарий, и имя блока
   он только объявляет потомкам. Класс блока экрана вешает хост через `host: { class: … }`.
 - **`justify-content: center` во flex-контейнере с `overflow-x` уводит первые элементы за

package/assets/rules/task-flow.md

@@ -73,6 +73,11 @@ description: Правило под «Закон о ведении работы»
   — признак; правила, тексты, обвязка и зависимости под него не подпадают. Обход — строка
   `**Поведение:** не меняется — <причина владельца>` в замысле; пустая причина не
   принимается.
+- **Гард замысла — нижняя граница, а не признак папки задачи.** Он требует её только под правку
+  кода приложения; нужна ли папка работе, которая туда не доходит, решает число заходов, а не
+  путь. Работа в один заход и один коммит целиком помещается в тело отчёта — так закрывается
+  разбор чужой папки. Работа с этапами и передачей папку заводит: между заходами её состояние
+  не держит ничто, кроме хода работы.
 - **Ход, в котором владельцу задан вопрос, не заканчивается, пока за этот же ход не читались
   законы и правила.** Чтением считается любой из трёх путей: загрузка правила, чтение файла
   законов или правил, поиск по ним. Отбивает гард разговора — на завершении хода, а не на