@rt-tools/agent-kit 0.11.0 → 0.13.0

package/assets/rules/deploy-flow.azure.md

@@ -0,0 +1,114 @@
+---
+name: deploy-flow
+kind: rule
+law: delivery
+description: Правило под «Закон о поставке» для дерева в Azure DevOps — та его часть, что про выкатку. Брать, когда правка едет на прод: слияние в главную ветку, конвейер, образы и их метки, чистка реестра, описание прода, цепочка миграций хранилища. Называет признак режима в образе, выкатку по sha коммита, глубину отката и сверку прода с главной веткой. Готовый код — в паттернах git-workflow-migration, git-workflow-restart, git-workflow-docker и git-workflow-secrets. Не брать на заведение задачи, ветки, коммит и заявку — это правило git-workflow.
+---
+
+# Выкатка — как это устроено здесь
+
+Правило под закон `docs/constitution/delivery.md` — та его часть, что про прод. Закон
+говорит, что должно быть верно; здесь — каким приёмом это держится в дереве, лежащем
+в Azure DevOps. Работа с очередью, ветка, коммит и заявка — правило `git-workflow` под тем же
+законом.
+
+## Как это называется здесь
+
+| В законе                         | Здесь                                                    |
+| -------------------------------- | -------------------------------------------------------- |
+| попадание правки в главную ветку | слияние PR; чем запускается выкатка — слиянием или ручным запуском, — называет компаньон рядом                                                                                                                                                                           |
+| образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                                                               |
+| изменение хранилища              | миграция в `prisma/migrations/<метка>_<имя>/`                                                                                                                                                                                          |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Ход
+
+Ход выкатки: что уезжает на прод, чем помечен образ и что делается со старыми.
+
+```mermaid
+flowchart TD
+    A[Слияние в главную ветку] --> B{Правка задела код}
+    B -->|Нет| C[Шаги сборки пропускаются по признаку состава правки]
+    B -->|Да| D[Образ собирается и метится sha того коммита]
+    D --> E{Хранилище меняется этой правкой}
+    E -->|Да| F[Цепочка миграций прогнана с пустого хранилища до слияния]
+    E -->|Нет| G[Образ выкатывается по sha, а не по метке «последний»]
+    F --> G
+    G --> H[Старые образы снимаются, три последних sha остаются глубиной отката]
+    H --> I{Прод отвечает тем, что выкачено}
+    I -->|Нет| J[Разбор выкатки: перезапуск идёт по sha, а не по последней метке]
+    I -->|Да| K[Сверка очереди работ читает последний прогон главной ветки]
+    C --> K
+    J --> K
+```
+
+## Как закон применяется здесь
+
+- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
+  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
+  не поднимает стенда, не снимает кадров и не собирает образов. Признак объявляется переменной
+  задания и считается один раз, а не переспрашивается в каждом условии. Пропущенный шаг виден в
+  прогоне пропущенным — молча выпавший читается как пройденный.
+- **Чем запускается выкатка, называет дерево, а не правило.** У одного дерева прод едет от
+  слияния, у другого — ручным запуском, и сказанное здесь безусловно врёт про второе: правило
+  приходит в контекст каждой сессии, и прочитавший его считает влитое выкаченным. Прод,
+  отставший от главной ветки на сотни коммитов, так и читался поломкой приложения. Строка стоит
+  в компаньоне рядом, вместе со способом спросить, что выкачено на самом деле.
+- **Выкатка идёт от слияния — переменные окружения, секреты и записи имён ставятся до него.**
+  Фильтры путей конвейера покрывают документы отдельно. Дерево с ручным запуском эту статью
+  читает иначе: там граница — сам запуск, и до него ставится то же самое.
+- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
+  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
+  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
+  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
+- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
+  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
+  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
+  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
+  через две выкатки, откатывается уже некуда.
+- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
+  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
+  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
+- **Правка конвейера прогоняется до слияния ручным запуском.** Конвейер запускается на любой
+  ветке, а задание выкатки прибито условием к главной: прогон ради проверки доходит до сборок и
+  там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
+  а не файл конвейера, — верность самого файла читается только по списку прогонов после пуша.
+- **PR проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
+  образов идут на конвейере проверки PR, выкатка — нет: её держит условие по главной ветке у
+  своего задания, а образ PR в реестр не уезжает.
+- **Расхождение прода с главной веткой видно сверкой очереди работ.** Рабочий элемент уходит из
+  очереди слиянием, но слияние — ещё не прод: отказавшая или незапущенная выкатка не трогает ни
+  элемент, ни его состояние, и заметить её неоткуда. Сверка спрашивает последнюю успешную выкатку и считает, на сколько от неё ушла главная
+  ветка. Прогон главной ветки для этого не годится: там, где выкатку запускают рукой, слияние
+  прод не двигает вовсе, и прогон о нём не говорит ничего — прод отставал на 476 коммитов, а
+  сверка молчала. Дерево, не назвавшее рабочего потока выкатки, сверки не получает, и она
+  говорит об этом вслух.
+- **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
+  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит.
+- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
+  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
+  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
+  двух местах разное.
+
+## Чего из закона здесь нет
+
+Состояние прода машине не видно: сверка очереди работ спрашивает последний прогон главной
+ветки и судит по нему, а отвечает ли прод той сборкой, которую он выкатил, не спрашивает
+никто. Держится это тем, кто выкатывал.
+
+Полноту чистки реестра не считает ничто: сценарий оставляет три последних sha, и промах в
+его отборе виден только тогда, когда диск сервера кончился.
+
+## Паттерны
+
+- `git-workflow-migration` — правка схемы хранилища и её миграций.
+- `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.

package/assets/rules/deploy-flow.github.md

@@ -0,0 +1,122 @@
+---
+name: deploy-flow
+kind: rule
+law: delivery
+description: Правило под «Закон о поставке» для дерева на GitHub — та его часть, что про выкатку. Брать, когда правка едет на прод: мерж в главную ветку, конвейер, образы и их метки, чистка реестра, описание прода, цепочка миграций хранилища. Называет признак режима в образе, выкатку по sha коммита, глубину отката и сверку прода с главной веткой. Готовый код — в паттернах git-workflow-migration, git-workflow-restart, git-workflow-docker и git-workflow-secrets. Не брать на заведение задачи, ветки, коммит и заявку — это правило git-workflow.
+---
+
+# Выкатка — как это устроено здесь
+
+Правило под закон `docs/constitution/delivery.md` — та его часть, что про прод. Закон
+говорит, что должно быть верно; здесь — каким приёмом это держится в дереве, лежащем
+на GitHub. Работа с очередью, ветка, коммит и заявка — правило `git-workflow` под тем же
+законом.
+
+## Как это называется здесь
+
+| В законе                         | Здесь                                                    |
+| -------------------------------- | -------------------------------------------------------- |
+| попадание правки в главную ветку | мерж PR; чем запускается выкатка — слиянием или ручным запуском, — называет компаньон рядом                                                                                                                               |
+| образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                        |
+| изменение хранилища              | миграция в `prisma/migrations/<метка>_<имя>/`                                                                                                                                                   |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Ход
+
+Ход выкатки: что уезжает на прод, чем помечен образ и что делается со старыми.
+
+```mermaid
+flowchart TD
+    A[Мерж в главную ветку] --> B{Правка задела код}
+    B -->|Нет| C[Шаги сборки пропускаются по признаку состава правки]
+    B -->|Да| D[Образ собирается и метится sha того коммита]
+    D --> E{Хранилище меняется этой правкой}
+    E -->|Да| F[Цепочка миграций прогнана с пустого хранилища до слияния]
+    E -->|Нет| G[Образ выкатывается по sha, а не по метке «последний»]
+    F --> G
+    G --> H[Старые образы снимаются, три последних sha остаются глубиной отката]
+    H --> I{Прод отвечает тем, что выкачено}
+    I -->|Нет| J[Разбор выкатки: перезапуск идёт по sha, а не по последней метке]
+    I -->|Да| K[Сверка очереди работ читает последний прогон главной ветки]
+    C --> K
+    J --> K
+```
+
+## Как закон применяется здесь
+
+- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
+  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
+  не поднимает стенда, не снимает кадров и не собирает образов. Признак считается один раз и
+  объявляется выводом шага, а не переспрашивается в каждом условии. Пропущенный шаг виден в
+  прогоне пропущенным — молча выпавший читается как пройденный.
+- **Чем запускается выкатка, называет дерево, а не правило.** У одного дерева прод едет от
+  мержа, у другого — ручным запуском, и сказанное здесь безусловно врёт про второе: правило
+  приходит в контекст каждой сессии, и прочитавший его считает влитое выкаченным. Прод,
+  отставший от главной ветки на сотни коммитов, так и читался поломкой приложения. Строка стоит
+  в компаньоне рядом, вместе со способом спросить, что выкачено на самом деле.
+- **Выкатка идёт от мержа — переменные окружения, секреты и записи имён ставятся до него.**
+  Исключения по путям покрывают только документы. Дерево с ручным запуском эту статью читает
+  иначе: там граница — сам запуск, и до него ставится то же самое.
+- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
+  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
+  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
+  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
+- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
+  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Убирает за собой и та машина, которая образы собирает.** Отбор у обеих один — своё имя
+  реестра, три последних sha, поднятые контейнеры остаются, — и зовётся он одним сценарием:
+  разойдясь, две чистки начали бы оставлять разное, а заметить это нечем. Отличаются они
+  хвостом: сервер снимает следом висячие слои и кэш сборки, машина сборки оставляет их себе,
+  иначе каждая сборка идёт как первая. Чистка на сборке не ждёт мержа: образ ветки занимает
+  столько же места, в реестр не уезжает вовсе и точкой отката не бывает.
+- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
+  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
+  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
+  через две выкатки, откатывается уже некуда.
+- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
+  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
+  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
+- **Правка конвейера прогоняется до мержа ручным запуском.** `workflow_dispatch` у выкатки
+  запускает её на любой ветке, а сама выкатка прибита условием к главной: прогон ради проверки
+  доходит до сборок и там кончается. Триггер регистрируется по главной ветке, поэтому правку,
+  которая его заводит или переносит, ручной запуск не покрывает. Прогон команд задания на своей
+  машине не покрывает её тоже: он проверяет команды, а не файл конвейера, — верность самого
+  файла читается только по списку прогонов после пуша.
+- **PR проверяется до мержа тем же конвейером, что и главная ветка.** Проверки и сборки
+  образов идут на событии `pull_request`, выкатка — нет: её держит условие по главной ветке у
+  своего задания, а образ PR в реестр не уезжает.
+- **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
+  мержем, но мерж — ещё не прод: отказавшая или незапущенная выкатка не трогает ни задачу, ни её
+  колонку, и заметить её неоткуда. Сверка спрашивает последнюю успешную выкатку и считает, на сколько от неё ушла главная
+  ветка. Прогон главной ветки для этого не годится: там, где выкатку запускают рукой, слияние
+  прод не двигает вовсе, и прогон о нём не говорит ничего — прод отставал на 476 коммитов, а
+  сверка молчала. Дерево, не назвавшее рабочего потока выкатки, сверки не получает, и она
+  говорит об этом вслух.
+- **Цепочка миграций прогоняется с пустого хранилища до мержа.** Порядок применения
+  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит.
+- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
+  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
+  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
+  двух местах разное.
+
+## Чего из закона здесь нет
+
+Состояние прода машине не видно: сверка очереди работ спрашивает последний прогон главной
+ветки и судит по нему, а отвечает ли прод той сборкой, которую он выкатил, не спрашивает
+никто. Держится это тем, кто выкатывал.
+
+Полноту чистки реестра не считает ничто: сценарий оставляет три последних sha, и промах в
+его отборе виден только тогда, когда диск сервера кончился.
+
+## Паттерны
+
+- `git-workflow-migration` — правка схемы хранилища и её миграций.
+- `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.

package/assets/rules/deploy-flow.gitlab.md

@@ -0,0 +1,116 @@
+---
+name: deploy-flow
+kind: rule
+law: delivery
+description: Правило под «Закон о поставке» для дерева на GitLab — та его часть, что про выкатку. Брать, когда правка едет на прод: слияние в главную ветку, конвейер, образы и их метки, чистка реестра, описание прода, цепочка миграций хранилища. Называет признак режима в образе, выкатку по sha коммита, глубину отката и сверку прода с главной веткой. Готовый код — в паттернах git-workflow-migration, git-workflow-restart, git-workflow-docker и git-workflow-secrets. Не брать на заведение задачи, ветки, коммит и заявку — это правило git-workflow.
+---
+
+# Выкатка — как это устроено здесь
+
+Правило под закон `docs/constitution/delivery.md` — та его часть, что про прод. Закон
+говорит, что должно быть верно; здесь — каким приёмом это держится в дереве, лежащем
+на GitLab. Работа с очередью, ветка, коммит и заявка — правило `git-workflow` под тем же
+законом.
+
+## Как это называется здесь
+
+| В законе                         | Здесь                                                    |
+| -------------------------------- | -------------------------------------------------------- |
+| попадание правки в главную ветку | слияние MR; чем запускается выкатка — слиянием или ручным запуском, — называет компаньон рядом                                                                                                                                               |
+| образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                              |
+| изменение хранилища              | миграция в `prisma/migrations/<метка>_<имя>/`                                                                                                                                                         |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Ход
+
+Ход выкатки: что уезжает на прод, чем помечен образ и что делается со старыми.
+
+```mermaid
+flowchart TD
+    A[Слияние в главную ветку] --> B{Правка задела код}
+    B -->|Нет| C[Шаги сборки пропускаются по признаку состава правки]
+    B -->|Да| D[Образ собирается и метится sha того коммита]
+    D --> E{Хранилище меняется этой правкой}
+    E -->|Да| F[Цепочка миграций прогнана с пустого хранилища до слияния]
+    E -->|Нет| G[Образ выкатывается по sha, а не по метке «последний»]
+    F --> G
+    G --> H[Старые образы снимаются, три последних sha остаются глубиной отката]
+    H --> I{Прод отвечает тем, что выкачено}
+    I -->|Нет| J[Разбор выкатки: перезапуск идёт по sha, а не по последней метке]
+    I -->|Да| K[Сверка очереди работ читает последний прогон главной ветки]
+    C --> K
+    J --> K
+```
+
+## Как закон применяется здесь
+
+- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
+  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
+  не поднимает стенда, не снимает кадров и не собирает образов. Правила `rules:changes` считают
+  это сами, но по путям, а не по составу правки — совпадение пути ещё не значит, что задета
+  сборка, поэтому признак объявляется явно и один раз. Пропущенный шаг виден в прогоне
+  пропущенным — молча выпавший читается как пройденный.
+- **Чем запускается выкатка, называет дерево, а не правило.** У одного дерева прод едет от
+  слияния, у другого — ручным запуском, и сказанное здесь безусловно врёт про второе: правило
+  приходит в контекст каждой сессии, и прочитавший его считает влитое выкаченным. Прод,
+  отставший от главной ветки на сотни коммитов, так и читался поломкой приложения. Строка стоит
+  в компаньоне рядом, вместе со способом спросить, что выкачено на самом деле.
+- **Выкатка идёт от слияния — переменные окружения, секреты и записи имён ставятся до него.**
+  Правила `only`/`rules` конвейера покрывают документы отдельно. Дерево с ручным запуском эту
+  статью читает иначе: там граница — сам запуск, и до него ставится то же самое.
+- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
+  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
+  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
+  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
+- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
+  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
+  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
+  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
+  через две выкатки, откатывается уже некуда.
+- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
+  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
+  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
+- **Правка конвейера прогоняется до слияния ручным запуском.** Конвейер запускается на любой
+  ветке, а задание выкатки прибито правилом к главной: прогон ради проверки доходит до сборок и
+  там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
+  а не файл конвейера, — верность самого файла читается только по списку конвейеров после
+  пуша, и синтаксис отдельно судит проверка `.gitlab-ci.yml` в проекте.
+- **PR проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
+  образов идут на конвейере запроса слияния, выкатка — нет: её держит правило по главной ветке
+  у своего задания, а образ PR в реестр не уезжает.
+- **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
+  слиянием, но слияние — ещё не прод: отказавшая или незапущенная выкатка не трогает ни задачу,
+  ни её список, и заметить её неоткуда. Сверка спрашивает последнюю успешную выкатку и считает, на сколько от неё ушла главная
+  ветка. Прогон главной ветки для этого не годится: там, где выкатку запускают рукой, слияние
+  прод не двигает вовсе, и прогон о нём не говорит ничего — прод отставал на 476 коммитов, а
+  сверка молчала. Дерево, не назвавшее рабочего потока выкатки, сверки не получает, и она
+  говорит об этом вслух.
+- **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
+  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит.
+- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
+  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
+  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
+  двух местах разное.
+
+## Чего из закона здесь нет
+
+Состояние прода машине не видно: сверка очереди работ спрашивает последний прогон главной
+ветки и судит по нему, а отвечает ли прод той сборкой, которую он выкатил, не спрашивает
+никто. Держится это тем, кто выкатывал.
+
+Полноту чистки реестра не считает ничто: сценарий оставляет три последних sha, и промах в
+его отборе виден только тогда, когда диск сервера кончился.
+
+## Паттерны
+
+- `git-workflow-migration` — правка схемы хранилища и её миграций.
+- `git-workflow-restart` — ручной перезапуск прода.
+- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
+- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.

package/assets/rules/doc-style.md

@@ -12,6 +12,9 @@ description: Правило под «Закон о документации пр
 Устройство спеков и слоёв документации — правило `spec-driven` под тем же законом; здесь
 только формулировки.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 | В законе                           | Здесь                                                                                                              |
@@ -58,42 +61,62 @@ flowchart TD
   которые едут в репозиторий: личный черновик, закрытый `.gitignore` или
   `.git/info/exclude`, проверка не читает — мёртвая ссылка в нём держала гейт пуша, хотя ни
   в одну ветку этот файл не попадёт.
+  <!-- rt-when: *.md -->
+
 - **Голое имя и каталог судятся наравне с полным путём.** Имя без каталога ищется по всему
   дереву, каталог — среди каталогов; дерево спрашивается у системы контроля версий, иначе
   каталоги, начинающиеся с точки, не видны и всё, что в них лежит, читалось бы как
   несуществующее. Половина строк в таблицах «Где это лежит» — как раз каталоги.
+  <!-- rt-when: *.md -->
+
 - **Описание прошлого из проверки путей выведено целиком.** Архив по устройству называет
   файлы, которых уже нет, и правкой это не лечится. Папка задачи выведена по той же причине:
   раздел находок в ходе работы перечисляет ровно то, чего в дереве нет.
+  <!-- rt-when: *.md -->
+
 - **Переносимый текст из сверки адресов выведен, как архив.** Закон, правило и паттерн написаны
   для любого дерева этого класса, и адреса в них принадлежат тому дереву, куда текст ложится:
   `libs/common/util` там, где корни зовутся иначе, — пример, а не мёртвая ссылка. Разложенную
   копию проверка узнаёт по шапке раскладки, исходник — по каталогу, названному в настройке; без
   этого сверка краснеет на полторы сотни строк, ни одна из которых не чинится здесь.
+  <!-- rt-when: *.md -->
+
 - **Указатель каталога сверяется с его содержимым обеими сторонами.** Записи каталог набирает
   быстрее, чем читают его указатель, и промах не виден ни в сборке, ни в браузере: запись,
   приехавшая слиянием соседней ветки, просто не попадает в таблицу. Сверенный руками указатель
   расходится снова через сутки.
+  <!-- rt-when: *.md -->
+
 - **Имя, названное затем, чтобы сказать «его нет», стоит в списке исключений поимённо.**
   Отличить такое упоминание от ссылки машине нечем, а текст без него теряет смысл: правило и
   замысел предупреждают именно о снятом. Туда же — то, что появляется только после сборки,
   имена веток и правила линтеров: выглядят адресом, адресом не являются.
+  <!-- rt-when: *.md -->
+
 - **Документ едет в том же коммите, что и правка, которую он описывает.** Обход — строка
   `Docs-skip: <причина>` в теле коммита; пустая причина не принимается.
+  <!-- rt-when: *.md -->
+
 - **Документ не длиннее предела длины.** Текст, который не влезает на экран целиком, дописывают
   в конец, не перечитав начала, — так в одном документе и оказываются два ответа на один вопрос.
-  Предел тот же, что у кода, и считается так же — все строки; выросший спек делится на
-  поддомены, а не переносит границу. Описание прошлого из счёта выведено: архив по устройству
+  Предел у текста свой, ниже, чем у кода, и считается так же — все строки; выросший спек
+  делится на поддомены, а не переносит границу. Два числа вместо одного заведены потому, что
+  тексту порог нужен раньше: у кода длину стережёт ещё и линтер, а у прозы — только это число. Описание прошлого из счёта выведено: архив по устройству
   перечисляет то, чего в дереве уже нет, а папка задачи умирает со слиянием.
+  <!-- rt-when: *.md -->
+
 - **Файл, уезжающий в описание прошлого, называет в шапке свой прежний адрес.** Записи архива
   ссылались на него, пока он был живым, и после переезда эти ссылки ведут в пустоту: проверка
   путей архив не читает вовсе, поэтому промах не краснеет никогда. Найти переехавшее нечем —
   имя записи архива с прежним адресом не совпадает, и поиск по нему её не показывает. Одна
   строка в шапке дешевле правки всех ссылающихся записей и прошлого не трогает.
+  <!-- rt-when: *.md -->
+
 - **Текст, называющий состояние машины, устаревает без единой правки в дереве.** Ловушка о том,
   что на машине установлено, верна в день, когда её пишут, и становится неправдой сама собой —
   ни одна сверка этого не видит: они читают дерево, а состарилась машина. Утверждение о машине
   пишется способом её спросить: команда и то, с чем сверять ответ, вместо снимка ответа.
+  <!-- rt-when: *.md -->
 
 ## Чего из закона здесь нет
 
@@ -127,77 +150,3 @@ flowchart TD
 
 Читается этот список раньше остального: правило говорит, как формулировать, а скил дерева — что
 у документа этого рода обязательно есть, вплоть до второго файла рядом.
-
-## Ловушки
-
-- **Оставшаяся работа не записывается в документ, а заводится задачей.** `docs/BACKLOG.md`
-  держит только то, что задачей не бывает: договорённости и решения, которые решено не
-  править. Признак — утверждение остаётся, если править его никто не собирается. «Сделать
-  потом» в плане, README или спеке — второй список работ: он расходится с бордой молча, а
-  разбирать его потом дороже, чем завести задачу сразу. Из 1411 строк документа действующими
-  оказались 71, и на разбор остальных ушла отдельная задача. Как разбирать накопившееся —
-  паттерн `doc-style-sweep`.
-- **Словарь действует и на разговор с владельцем, не только на файлы.** Он приходит в контекст
-  на запуске сессии, поэтому «не читал» основанием не бывает. Слово из левой колонки «Так не
-  пишем» всплывало именно в ответах: в дереве его уже вычистили, а в PR о сделанном оно
-  оставалось, и владелец читал ровно то слово, от которого отказались.
-- **Термин берётся из `docs/GLOSSARY.md`, а не придумывается на месте.** Слова, которого там
-  нет, у читателя нет тоже: «журнал приложения» простоял в спеке почты, пока владелец не
-  спросил, что это, — оказалось, логи бэкенда, а слово «журнал» здесь уже занято журналом
-  событий. Новое слово либо заводится в словаре вместе с правкой, либо заменяется тем, что
-  уже есть.
-- **Проход по словарю глазами слово не находит.** «Формулировки приведены к словарю» означает
-  ровно те строки, которые в тот момент читали: «спека» пережила такой проход и осталась в
-  соседней строке того же файла. Слово из левой колонки таблицы «Так не пишем» вычищается
-  грепом по всему дереву, а не вычиткой. Форма задаётся точно: «спек» — документ — склоняется
-  в «спека» и «спеки» тоже, и совпадений по корню законных больше, чем нарушений; ищутся
-  сочетания («спеки на … нет», «спека проверяет»), а не корень.
-- **Снятое имя вычищается одним грепом по всему дереву:** правила, их зеркала в скилах,
-  документы и комментарии. Описание того, чего в коде уже нет, читается как действующее
-  указание.
-- **У снятого слова второе значение возвращается после сплошной замены, а не обходится до
-  неё.** Слово снимают ровно потому, что оно стояло над двумя вещами, и второе значение при
-  этом остаётся законным. Отобрать его заранее нечем: какое из двух значений в строке, видно
-  только по соседнему тексту, а строк бывают сотни. Порядок обратный — сплошная замена, затем
-  сплошной просмотр самой правки, и найденное второе значение возвращается поимённо. Из 353
-  замен так вернулись шесть, и две первые были поломкой: сверка печатала новое имя дважды
-  подряд, а комментарий обещал «поломку вместо PR о том, что долгов нет». Просматривается
-  правка, а не дерево после неё: в дереве обе стороны выглядят одинаково верными.
-- **Поиск по дереву не покрывает того, что уже уехало наружу.** Заголовок задачи и её тело,
-  заголовок PR и его тело, заголовки коммитов лежат вне файлов, и проверки текстов их не
-  читают вовсе. Вычистив слово в дереве, обходят те же места в очереди работ и в истории:
-
-    ```bash
-    <клиент хостинга> api "<путь к PR>" --jq '.title, .body' | grep -i '<слово>'
-    <клиент хостинга> api "<путь к задаче>" --jq '.title, .body' | grep -i '<слово>'
-    git log --format='%s%n%b' <база>..HEAD | grep -i '<слово>'
-    ```
-
-    Заголовок PR правится вызовом хостинга, заголовок коммита — только переписыванием ветки,
-    поэтому его проверяют до пуша. Выдуманное слово было вычищено из трёх файлов и объявлено
-    снятым, а в заголовке PR и в заголовке коммита осталось — владелец прочитал именно его.
-
-- **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет
-  внутри одной ветки: «шестнадцать пар» стало неправдой через два коммита после того, как
-  было написано, и нашёл это владелец, а не проверка. Число, которое придётся пересчитывать
-  при каждой правке, лучше не писать вовсе. Число, полученное разбором текста, сверяется на
-  выборке руками до того, как его называют: разбор, не знающий второй формы записи, ошибается
-  молча — «51 пункт без задачи» оказался шестью, потому что номер стоял и отдельной строкой, и
-  в заголовке подраздела.
-- **Названная в тексте проверка запускается, а не пересказывается.** «Проверка есть» и
-  «проверка проходит» — разные утверждения, и второго в тексте обычно нет вовсе. Из четырёх
-  проверок, названных правилом, три оказались не в том состоянии, в каком текст их описывает:
-  одна отдавала полтора десятка замечаний, вторая переписывала файлы самим запуском, третья
-  была красной и роняла общую сводку вместе с собой. Ни одна из трёх не входила в выкатку,
-  поэтому молчание было полным. Проверку, которая переписывает файлы, запускают на чистом
-  дереве: иначе её правки уедут чужим коммитом.
-- **Сделанность читается по дереву, а не по тексту, который о ней написан.** Это верно в обе
-  стороны: строка про README обеих либ была вычеркнута как сделанная, а README остался с
-  прежним числом импортёров; задача, названная владельцу несделанной, оказалась наполовину
-  закрытой и покрытой сценариями хука. Пункт плана и тело задачи описывают день, когда их
-  написали, и с тех пор не менялись.
-- **Комментарий в файле — такое же утверждение, как строка в документе.** Обоснование «строки
-  идут во всю ширину панели, иначе подсветка обрывается» было выдумано, прожило три сессии и
-  каждый раз читалось как основание вёрстку не трогать.
-- **Чужие проекты не упоминаются нигде** — ни имени репозитория, ни «портировано из», ни
-  ссылок на его файлы. Описывается то, что код делает здесь, в терминах этого проекта.