@rt-tools/agent-kit 0.5.3 → 0.6.0

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

@@ -2,7 +2,7 @@
 name: git-workflow
 kind: rule
 law: delivery
-description: Правило под «Закон о поставке» для дерева в Azure DevOps. Брать на заведение задачи, ветки, коммит, пуш, создание PR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет рабочий элемент как начало работы, его состояние как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration и git-workflow-restart.
+description: Правило под «Закон о поставке» для дерева в Azure DevOps. Брать на заведение задачи, ветки, коммит, пуш, создание PR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет рабочий элемент как начало работы, его состояние как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration, git-workflow-restart, git-workflow-docker и git-workflow-secrets.
 ---
 
 # Поставка — как это устроено здесь
@@ -63,6 +63,11 @@ description: Правило под «Закон о поставке» для д
 - **Задачи, чинящиеся одной правкой, сливаются до слияния ветки.** Вторая закрывается как
   дубликат, а недостающее из неё дописывается в первую. После слияния слить уже нельзя: ветка
   въехала, и откатывается она целиком.
+- **Работа, которую одним заходом не закрыть, помечена в двух местах, и они сверяются.** Метка
+  на доске и строка о заходах с передачей в линии работ говорят одно и то же двум читателям:
+  исполнитель открывает карточку раньше, чем линию, а планирует по линии. Одна пометка без
+  другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
+  законно не делится: пометка объёма правом делить не становится.
 - **Слияние в главную ветку выкатывает прод.** Фильтры путей конвейера покрывают документы
   отдельно, поэтому переменные окружения, секреты и записи имён ставятся до слияния, а не
   после.
@@ -72,6 +77,24 @@ description: Правило под «Закон о поставке» для д
   умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
 - **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
   от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
+  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
+  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
+  через две выкатки, откатывается уже некуда.
+- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
+  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
+  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
+- **Правка конвейера прогоняется до слияния ручным запуском.** Конвейер запускается на любой
+  ветке, а задание выкатки прибито условием к главной: прогон ради проверки доходит до сборок и
+  там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
+  а не файл конвейера, — верность самого файла читается только по списку прогонов после пуша.
+- **Отчёт проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
+  образов идут на конвейере проверки PR, выкатка — нет: её держит условие по главной ветке у
+  своего задания, а образ отчёта в реестр не уезжает.
+- **Расхождение прода с главной веткой видно сверкой очереди работ.** Рабочий элемент уходит из
+  очереди слиянием, но слияние — ещё не прод: отказавшая выкатка не трогает ни элемент, ни его
+  состояние, и заметить её неоткуда. Сверка спрашивает последний прогон главной ветки и судит
+  только завершённый: идущий ещё может кончиться выкаткой.
 - **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
   лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
   ветки, начатой раньше, встаёт перед той, от которой зависит.
@@ -81,6 +104,10 @@ description: Правило под «Закон о поставке» для д
   заголовок читается списком, а свободный текст — только целиком.
 - **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы
   стилей вовсе, и правила оформления без второго прогона не проверяет ничто.
+- **Сборка входит в набор наравне с линтом и юнитами.** Линтер типов не читает, а юниты читают
+  только то, что импортировано тестом: ошибка типов в непокрытом коде доживает до сборки
+  образа, то есть до слияния. Четыре слияния подряд так и уехали в главную ветку, ломая
+  выкатку.
 - **Рабочий элемент привязывается к PR при создании, а не после.** `az repos pr create`
   принимает `--work-items`; привязка второй командой обходится молча, когда у токена нет права
   править чужой элемент, и PR остаётся ни с чем не связанным.
@@ -124,6 +151,8 @@ description: Правило под «Закон о поставке» для д
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
 
 ## Ловушки
 
@@ -148,6 +177,21 @@ description: Правило под «Закон о поставке» для д
   записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
   работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
   смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** Прогон
+  заводится и кончается на разборе файла, не начав ни одного задания: в списке он стоит
+  отказом, а внутри нет ни задания, ни лога — читается только длительность. Поэтому список
+  прогонов ветки смотрится тем же движением, что и пуш: `az pipelines runs list` по своей
+  ветке.
+- **`online` у агента на своей машине означает запущенный процесс, а не работающий конвейер.**
+  Две стороны сходятся отдельно: требования заданий и возможности самого агента в его пуле.
+  Пока пересечения нет, агент стоит `online` и не берёт ничего, а задания ждут размещённого
+  пула — по состоянию это выглядит настроенным. Владельцу называют выполненное задание с его
+  номером, а не строку состояния.
+- **Вход в реестр образов из агента, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
 - **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
   разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
   входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,

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

@@ -2,7 +2,7 @@
 name: git-workflow
 kind: rule
 law: delivery
-description: Правило под «Закон о поставке» для дерева на GitHub. Брать на заведение задачи, ветки, коммит, пуш, создание PR, мерж, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration и git-workflow-restart.
+description: Правило под «Закон о поставке» для дерева на GitHub. Брать на заведение задачи, ветки, коммит, пуш, создание PR, мерж, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration, git-workflow-restart, git-workflow-docker и git-workflow-secrets.
 ---
 
 # Поставка — как это устроено здесь
@@ -73,6 +73,11 @@ description: Правило под «Закон о поставке» для д
 - **Задачи, чинящиеся одной правкой, сливаются до мержа.** Вторая стирается вместе с номером,
   а недостающее из неё дописывается в первую. После мержа слить уже нельзя: ветка въехала, и
   откатывается она целиком.
+- **Работа, которую одним заходом не закрыть, помечена в двух местах, и они сверяются.** Метка
+  на борде и строка о заходах с передачей в линии работ говорят одно и то же двум читателям:
+  исполнитель открывает карточку раньше, чем линию, а планирует по линии. Одна пометка без
+  другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
+  законно не делится: пометка объёма правом делить не становится.
 - **Мерж в главную ветку выкатывает прод.** Исключения по путям покрывают только документы,
   поэтому переменные окружения, секреты и записи имён ставятся до мержа, а не после.
 - **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
@@ -81,6 +86,26 @@ description: Правило под «Закон о поставке» для д
   умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
 - **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
   от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
+  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
+  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
+  через две выкатки, откатывается уже некуда.
+- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
+  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
+  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
+- **Правка конвейера прогоняется до мержа ручным запуском.** `workflow_dispatch` у выкатки
+  запускает её на любой ветке, а сама выкатка прибита условием к главной: прогон ради проверки
+  доходит до сборок и там кончается. Триггер регистрируется по главной ветке, поэтому правку,
+  которая его заводит или переносит, ручной запуск не покрывает. Прогон команд задания на своей
+  машине не покрывает её тоже: он проверяет команды, а не файл конвейера, — верность самого
+  файла читается только по списку прогонов после пуша.
+- **Отчёт проверяется до мержа тем же конвейером, что и главная ветка.** Проверки и сборки
+  образов идут на событии `pull_request`, выкатка — нет: её держит условие по главной ветке у
+  своего задания, а образ отчёта в реестр не уезжает.
+- **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
+  мержем, но мерж — ещё не прод: отказавшая выкатка не трогает ни задачу, ни её колонку, и
+  заметить её неоткуда. Сверка спрашивает последний прогон главной ветки и судит только
+  завершённый: идущий ещё может кончиться выкаткой.
 - **Цепочка миграций прогоняется с пустого хранилища до мержа.** Порядок применения
   лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
   ветки, начатой раньше, встаёт перед той, от которой зависит.
@@ -90,6 +115,9 @@ description: Правило под «Закон о поставке» для д
   заголовок читается списком, а свободный текст — только целиком.
 - **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы
   стилей вовсе, и правила оформления без второго прогона не проверяет ничто.
+- **Сборка входит в набор наравне с линтом и юнитами.** Линтер типов не читает, а юниты читают
+  только то, что импортировано тестом: ошибка типов в непокрытом коде доживает до сборки
+  образа, то есть до мержа. Четыре мержа подряд так и уехали в главную ветку, ломая выкатку.
 - **Автор PR не может быть его ревьювером.** Запрос разбора на самого себя GitHub принимает и
   молча не создаёт — разбор при этом выглядит запрошенным.
 - **Метки, исполнитель и ревьювер PR ставятся вызовами `gh api`, а не `gh pr edit`.** На
@@ -131,6 +159,8 @@ description: Правило под «Закон о поставке» для д
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
 
 ## Ловушки
 
@@ -154,6 +184,27 @@ description: Правило под «Закон о поставке» для д
   записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
   работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
   смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** GitHub
+  заводит такой прогон и на ветке, на которую ни один триггер не подписан: в списке он стоит
+  отказом, а внутри у него нет ни задания, ни лога — читается только длительность. Поэтому
+  список прогонов ветки смотрится тем же движением, что и пуш — `gh run list --branch <ветка>`.
+  Один такой отказ простоял в списке до мержа, и на него никто не посмотрел: выкатка после
+  мержа отказала ровно тем же.
+- **Контекст `runner` в `env` задания отбивает весь файл конвейера.** Там доступны только
+  `github`, `needs`, `strategy`, `matrix`, `vars`, `secrets` и `inputs`; `runner` появляется на
+  уровне шага, где то же значение приходит переменной окружения. Такой файл не принимается
+  вовсе: прогон кончается за ноль секунд, не начав ни одного задания. Разбор YAML этого не
+  ловит — синтаксис верный, а доступность контекстов синтаксисом не является.
+- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
+  конвейер.** Две стороны сходятся отдельно: `runs-on` у заданий и метки самого раннера. Пока
+  пересечения нет, раннер стоит `online` и не берёт ничего, а задания уходят в облако — по
+  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
+  не строку состояния.
+- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
 - **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
   разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
   входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,

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,10 @@ description: Правило под «Закон о поставке» для д
   заголовок читается списком, а свободный текст — только целиком.
 - **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы
   стилей вовсе, и правила оформления без второго прогона не проверяет ничто.
+- **Сборка входит в набор наравне с линтом и юнитами.** Линтер типов не читает, а юниты читают
+  только то, что импортировано тестом: ошибка типов в непокрытом коде доживает до сборки
+  образа, то есть до слияния. Четыре слияния подряд так и уехали в главную ветку, ломая
+  выкатку.
 - **Слияние по кнопке «Merge when pipeline succeeds» не заменяет проверок до пуша.** Конвейер
   видит только то, что уже отправлено, а отправленная красная ветка занимает очередь работ и
   выглядит готовой к разбору.
@@ -121,6 +149,8 @@ description: Правило под «Закон о поставке» для д
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
 
 ## Ловушки
 
@@ -144,6 +174,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/ownership-scope.md

@@ -59,5 +59,8 @@ description: Правило под «Закон о владеющей сущно
   вызывающего:** первое отвечает `FailedPrecondition`, второе — `NotFound`.
 - Таблица владеющих сущностей читается целиком одним запросом — она маленькая, и выборки ей не
   нужно.
-- Выбор сущности стоит в шапке и действует на разделы, которые говорят об одной. Снаружи выбора
-  нет: пользователь приходит на страницу конкретной.
+- **Выбор сущности живёт в общем сторе, а рисует переключатель тот экран, которому он нужен.**
+  Выбор переживает переход между разделами, но экран без своего переключателя показывает то,
+  что выбрали на другом, — и это читается как чужие числа в своём разделе. Где переключатель
+  стоит, названо в именах дерева; снаружи выбора нет вовсе: пользователь приходит на страницу
+  конкретной сущности.