@rt-tools/agent-kit 0.11.0 → 0.13.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, git-workflow-docker и git-workflow-secrets.
+description: Правило под «Закон о поставке» для дерева в Azure DevOps. Брать на заведение задачи, ветки, коммит, пуш, создание PR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет рабочий элемент как начало работы, его состояние как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-pr, git-workflow-merge. Выкатка, образы и миграции — правило deploy-flow.
 ---
 
 # Поставка — как это устроено здесь
@@ -12,6 +12,9 @@ description: Правило под «Закон о поставке» для д
 учётная запись машинной работы и области коммита — при этом дереве, в `implementation.md`
 рядом: их не угадать, и общими они не бывают.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 | В законе                         | Здесь                                                                                                                                                                                                                                  |
@@ -23,9 +26,6 @@ description: Правило под «Закон о поставке» для д
 | состояние задачи в очереди работ | поле `State` рабочего элемента: `New` у заведённого, `Active` у взятого в работу, `Resolved` у ждущего разбора. Набор состояний зависит от процесса проекта и назван в `implementation.md`; закрытая задача уходит из очереди слиянием |
 | PR о задаче                      | заголовок PR `[<номер>] <Что сделано>` — тот же номер, что у рабочего элемента, и его название, переведённое в сделанное; тип и область коммита сюда не идут                                                                           |
 | обсуждение правки                | разбор PR: ревьювер — владелец репозитория, исполнитель — учётная запись машинной работы, метки — те же, что у рабочего элемента                                                                                                       |
-| попадание правки в главную ветку | слияние PR; оно же запускает выкатку — `azure-pipelines.yml`                                                                                                                                                                           |
-| образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                                                               |
-| изменение хранилища              | миграция в `prisma/migrations/<метка>_<имя>/`                                                                                                                                                                                          |
 | запись о правке                  | коммит формата `type(scope): description` — типы `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`, `perf`; области — в `implementation.md`                                                                                  |
 | автор машинной работы            | отдельная учётная запись; её имя и место токена — в `implementation.md`. Токен лежит вне репозитория                                                                                                                                   |
 
@@ -128,11 +128,6 @@ flowchart TD
   не нужна вовсе, а заведённая живёт своей жизнью: состояния под неё нет, из очереди она не
   уходит и остаётся в ней после слияния навсегда. Находит такие сверка очереди — строкой на
   каждую.
-- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
-  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
-  не поднимает стенда, не снимает кадров и не собирает образов. Признак объявляется переменной
-  задания и считается один раз, а не переспрашивается в каждом условии. Пропущенный шаг виден в
-  прогоне пропущенным — молча выпавший читается как пройденный.
 - **Отставшее состояние находится сверкой очереди, а не глазами.** Сверка судит состояние по
   PR в обе стороны: открытый PR при элементе не в разборе и разбор без открытого PR — оба
   расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на доске нет.
@@ -144,36 +139,6 @@ flowchart TD
   исполнитель открывает карточку раньше, чем замысел эпика, а планирует по замыслу. Одна пометка без
   другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
   законно не делится: пометка объёма правом делить не становится.
-- **Слияние в главную ветку выкатывает прод.** Фильтры путей конвейера покрывают документы
-  отдельно, поэтому переменные окружения, секреты и записи имён ставятся до слияния, а не
-  после.
-- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
-  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
-  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
-  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
-- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
-  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
-- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
-  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
-  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
-  через две выкатки, откатывается уже некуда.
-- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
-  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
-  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
-- **Правка конвейера прогоняется до слияния ручным запуском.** Конвейер запускается на любой
-  ветке, а задание выкатки прибито условием к главной: прогон ради проверки доходит до сборок и
-  там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
-  а не файл конвейера, — верность самого файла читается только по списку прогонов после пуша.
-- **PR проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
-  образов идут на конвейере проверки PR, выкатка — нет: её держит условие по главной ветке у
-  своего задания, а образ PR в реестр не уезжает.
-- **Расхождение прода с главной веткой видно сверкой очереди работ.** Рабочий элемент уходит из
-  очереди слиянием, но слияние — ещё не прод: отказавшая выкатка не трогает ни элемент, ни его
-  состояние, и заметить её неоткуда. Сверка спрашивает последний прогон главной ветки и судит
-  только завершённый: идущий ещё может кончиться выкаткой.
-- **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
-  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
-  ветки, начатой раньше, встаёт перед той, от которой зависит.
 - **Документ едет в том же коммите, что и правка.** Обход — строка `Docs-skip: <причина>` в
   теле коммита; пустая причина не принимается.
 - **Заголовок коммита сверяется с форматом на месте.** Разобранный по типу и области
@@ -219,10 +184,6 @@ flowchart TD
   репозитории сценария наследует общий конфиг: если включена подпись, git идёт в агент ключей,
   а заблокированный агент роняет весь набор — со стороны это выглядит сломанным гардом. Автор,
   почта и подпись передаются флагами `-c` прямо в команду.
-- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
-  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
-  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
-  двух местах разное.
 
 ## Чего из закона здесь нет
 
@@ -249,54 +210,7 @@ flowchart TD
 
 ## Паттерны
 
-- `git-workflow-commit` — рабочий элемент, ветка, коммит, пуш и PR от учётной записи машинной
+- `git-workflow-commit` — рабочий элемент, ветка, коммит и пуш от учётной записи машинной работы.
+- `git-workflow-pr` — открытие PR, черновик и его снятие, тело, ревьювер, привязка к элементу.
   работы.
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
-- `git-workflow-migration` — правка схемы хранилища и её миграций.
-- `git-workflow-restart` — ручной перезапуск прода.
-- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
-- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
-
-## Ловушки
-
-- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
-  становится вторым рабочим элементом, здесь нет: делится то, что придётся откатывать порознь.
-  Сплошная правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать
-  два рабочих элемента, закрывать два PR и переносить коммиты по одному с двумя конфликтами.
-  Одна из трёх не дала коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей
-  под ветку тоже.
-- **Рабочий элемент заводится командой, а не вызовами подряд.** Доска показывает элементы своей
-  области и итерации, и заведённый мимо них в очереди работ не виден: со стороны это выглядит
-  так же, как незаведённый. Команда заведения ставит все поля разом — род, состояние,
-  исполнителя, область и итерацию, — и печатает готовую строку заведения ветки. Замеченный по
-  ходу дефект проходит тот же путь.
-- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
-  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
-- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
-  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
-  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
-  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
-- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
-  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
-  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
-  смена записи ради пуша утекла в публикацию — 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, git-workflow-docker и git-workflow-secrets.
+description: Правило под «Закон о поставке» для дерева на GitHub. Брать на заведение задачи, ветки, коммит, пуш, создание PR, мерж, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-pr, git-workflow-merge. Выкатка, образы и миграции — правило deploy-flow.
 ---
 
 # Поставка — как это устроено здесь
@@ -12,6 +12,9 @@ description: Правило под «Закон о поставке» для д
 учётная запись машинной работы и области коммита — при этом дереве, в `implementation.md`
 рядом: их не угадать, и общими они не бывают.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 | В законе                         | Здесь                                                                                                                                                                                           |
@@ -24,9 +27,6 @@ description: Правило под «Закон о поставке» для д
 | состояние задачи в очереди работ | колонка борды — поле «Status»: заведённая, взятая в работу, ждущая разбора. Имена колонок — в `implementation.md`; закрытая задача уходит из очереди мержем, а не переводом в последнюю колонку |
 | PR о задаче                      | заголовок PR `[<КЛЮЧ>-<номер>] <Что сделано>` — тот же номер, что у задачи, и её название, переведённое в сделанное; тип и область коммита сюда не идут                                         |
 | обсуждение правки                | разбор PR: ревьювер — владелец репозитория, исполнитель — учётная запись машинной работы, метки — те же, что у задачи                                                                           |
-| попадание правки в главную ветку | мерж PR; он же запускает выкатку — `.github/workflows/deploy.yml`                                                                                                                               |
-| образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                        |
-| изменение хранилища              | миграция в `prisma/migrations/<метка>_<имя>/`                                                                                                                                                   |
 | запись о правке                  | коммит формата `type(scope): description` — типы `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`, `perf`; области — в `implementation.md`                                           |
 | автор машинной работы            | отдельная учётная запись; её имя и место токена — в `implementation.md`. Токен лежит вне репозитория                                                                                            |
 
@@ -123,11 +123,6 @@ flowchart TD
   под неё нет, из очереди она не уходит и остаётся в ней после слияния навсегда. Заводится она
   либо встроенным правилом борды, либо рукой; и то и другое выключается, а накопившееся
   снимается. Находит их сверка очереди — строкой на каждую.
-- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
-  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
-  не поднимает стенда, не снимает кадров и не собирает образов. Признак считается один раз и
-  объявляется выводом шага, а не переспрашивается в каждом условии. Пропущенный шаг виден в
-  прогоне пропущенным — молча выпавший читается как пройденный.
 - **Отставшая колонка находится сверкой очереди, а не глазами.** Сверка судит колонку по
   PR в обе стороны: открытый PR при задаче не в разборе и разбор без открытого PR — оба
   расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на борде нет.
@@ -139,36 +134,6 @@ flowchart TD
   исполнитель открывает карточку раньше, чем замысел эпика, а планирует по замыслу. Одна пометка без
   другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
   законно не делится: пометка объёма правом делить не становится.
-- **Мерж в главную ветку выкатывает прод.** Исключения по путям покрывают только документы,
-  поэтому переменные окружения, секреты и записи имён ставятся до мержа, а не после.
-- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
-  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
-  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
-  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
-- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
-  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
-- **Убирает за собой и та машина, которая образы собирает.** Отбор у обеих один — своё имя
-  реестра, три последних sha, поднятые контейнеры остаются, — и зовётся он одним сценарием:
-  разойдясь, две чистки начали бы оставлять разное, а заметить это нечем. Отличаются они
-  хвостом: сервер снимает следом висячие слои и кэш сборки, машина сборки оставляет их себе,
-  иначе каждая сборка идёт как первая. Чистка на сборке не ждёт мержа: образ ветки занимает
-  столько же места, в реестр не уезжает вовсе и точкой отката не бывает.
-- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
-  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
-  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
-  через две выкатки, откатывается уже некуда.
-- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
-  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
-  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
-- **Правка конвейера прогоняется до мержа ручным запуском.** `workflow_dispatch` у выкатки
-  запускает её на любой ветке, а сама выкатка прибита условием к главной: прогон ради проверки
-  доходит до сборок и там кончается. Триггер регистрируется по главной ветке, поэтому правку,
-  которая его заводит или переносит, ручной запуск не покрывает. Прогон команд задания на своей
-  машине не покрывает её тоже: он проверяет команды, а не файл конвейера, — верность самого
-  файла читается только по списку прогонов после пуша.
-- **PR проверяется до мержа тем же конвейером, что и главная ветка.** Проверки и сборки
-  образов идут на событии `pull_request`, выкатка — нет: её держит условие по главной ветке у
-  своего задания, а образ PR в реестр не уезжает.
 - **Вершина открытого PR без прогона видна сверкой очереди работ.** Страница PR без прогона
   выглядит так же, как страница с зелёным: цвета у неё нет ни там, ни там, — и вершину, за
   которой прогон не встал, замечали только тем, что открывали список прогонов руками. Сверка
@@ -177,7 +142,12 @@ flowchart TD
 - **Черновик при зелёном прогоне на вершине — расхождение сверки.** У черновика кнопка слияния
   заблокирована самим хостингом: зелёная страница PR владельцу ничего не разрешает, а список, в
   котором всё серое, читается как «работа не сделана». Гард снятия черновика сюда не достаёт —
-  он судит один ход и молчит, пока ветка везёт папку своей задачи.
+  он судит один ход, а PR стоит в очереди днями.
+- **Открытие PR отбивается, пока ветка везёт папку своей задачи.** Уборка стоит до открытия, а
+  не после одобрения: кнопку слияния нажимает человек на странице хостинга, где гардов нет
+  вовсе, и вливает он, как только видит зелёное. Отказ на слиянии остаётся вторым рубежом — он
+  ловит слияние, идущее командой, — но первым спрашивается открытие: это последняя точка, где
+  отказ ещё виден тому, кто может его выполнить.
 - **Конфликтующий открытый PR — расхождение сверки очереди работ.** Конфликт приезжает в
   отданный PR чужим слиянием, без единого действия автора: основание, проверенное на открытии,
   устаревает в ту минуту, когда владелец влил соседнюю работу. Гард снятия черновика сюда не
@@ -185,13 +155,6 @@ flowchart TD
   метку хостинг показывает только внутри самого PR. Непосчитанная сливаемость расхождением не
   считается: хостинг считает её заново после каждой правки главной ветки, и строка на
   «ещё не посчитано» краснела бы на каждой свежей вершине.
-- **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
-  мержем, но мерж — ещё не прод: отказавшая выкатка не трогает ни задачу, ни её колонку, и
-  заметить её неоткуда. Сверка спрашивает последний прогон главной ветки и судит только
-  завершённый: идущий ещё может кончиться выкаткой.
-- **Цепочка миграций прогоняется с пустого хранилища до мержа.** Порядок применения
-  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
-  ветки, начатой раньше, встаёт перед той, от которой зависит.
 - **Документ едет в том же коммите, что и правка.** Обход — строка `Docs-skip: <причина>` в
   теле коммита; пустая причина не принимается.
 - **Заголовок коммита сверяется с форматом на месте.** Разобранный по типу и области
@@ -269,6 +232,14 @@ flowchart TD
   на них один. Исполнитель сливает свой PR только тогда, когда человек сказал это прямо и про
   этот PR; сказанное об одном PR на следующий не переносится, а молчание разрешением не
   бывает. Работа кончается PR, с которого снят черновик, и в ответе называется его номер.
+- **Личность вызова, открывающего заявку, стережёт гард поставки, а не память исполнителя.**
+  Она приходит окружением, и из текста команды видна только явной подстановкой токена — её гард
+  и требует, называя переменную и готовую строку; дерево, не назвавшее машинной записи,
+  требования не получает. Ответ хостинга об авторе он спрашивает позже, на снятии черновика:
+  это последний ход, где промах ещё исправим — влитую заявку не переоткрыть, а автора у неё не
+  сменить. Прежде обе стороны держались статьёй и разбором происшествия, и промах повторился на
+  третий день.
+
 - **Автор PR не может быть его ревьювером.** Запрос разбора на самого себя GitHub принимает и
   молча не создаёт — разбор при этом выглядит запрошенным. Поэтому в разборе считаются только
   запрос и отзыв не от автора: гард снятия черновика читает состояние PR именно так.
@@ -291,10 +262,6 @@ flowchart TD
   репозитории сценария наследует общий конфиг: если включена подпись, git идёт в агент ключей,
   а заблокированный агент роняет весь набор — со стороны это выглядит сломанным гардом. Автор,
   почта и подпись передаются флагами `-c` прямо в команду.
-- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
-  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
-  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
-  двух местах разное.
 
 ## Чего из закона здесь нет
 
@@ -317,81 +284,6 @@ flowchart TD
 
 ## Паттерны
 
-- `git-workflow-commit` — задача, ветка, коммит, пуш и PR от учётной записи машинной работы.
+- `git-workflow-commit` — задача, ветка, коммит и пуш от учётной записи машинной работы.
+- `git-workflow-pr` — открытие PR, черновик и его снятие, тело, ревьювер, метки, состояние.
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
-- `git-workflow-migration` — правка схемы хранилища и её миграций.
-- `git-workflow-restart` — ручной перезапуск прода.
-- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
-- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
-
-## Ловушки
-
-- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
-  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
-  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
-  закрывать два PR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
-  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
-- **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
-  привязана, и задача попадает на неё только явным добавлением: две задачи так и простояли вне
-  очереди работ, потому что шаг переписывали руками. Команда заведения делает все четыре — issue,
-  номер в его заголовке, добавление на борду, начальную колонку, — и печатает готовую строку
-  заведения ветки. Замеченный по ходу дефект проходит тот же путь.
-- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
-  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
-- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
-  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
-  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
-  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
-- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
-  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
-  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
-  смена записи ради пуша утекла в публикацию — PR вышел от владельца. Разница между читающим и
-  пишущим вызовом в самом тексте команды не видна: личность приходит окружением, поэтому у
-  вызова на запись токен называется явно, а открытая заявка проверяется ответом хостинга о её
-  авторе — напечатанная ссылка говорит, что заявка создана, и молчит о том, кем. Чинится это
-  только переоткрытием: автора у заявки не сменить.
-- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** GitHub
-  заводит такой прогон и на ветке, на которую ни один триггер не подписан: в списке он стоит
-  отказом, а внутри у него нет ни задания, ни лога — читается только длительность. Поэтому
-  список прогонов ветки смотрится тем же движением, что и пуш — `gh run list --branch <ветка>`.
-  Один такой отказ простоял в списке до мержа, и на него никто не посмотрел: выкатка после
-  мержа отказала ровно тем же.
-- **Прогон, не вставший на пуш, возвращается повтором события, а не разбором ветки.** Замером
-  проверены обе законные дороги: и открытие PR, и пуш в уже открытый PR прогон заводят —
-  текстовый коммит и учётная запись, которой пушат, тут ни при чём. Пропавшие события пришлись
-  на час, когда хостинг отвечал `429` на загрузке действия и `503` на API, а списком прогонов
-  «не завёлся» от «не создан» не отличить. Поэтому вершину без прогона называет сверка очереди
-  работ, а событие возвращается новым коммитом либо перезакрытием PR.
-- **Красное на шаге подготовки задания — отказ хостинга, а не дефект ветки.** Раннер не смог
-  скачать действие чекаута и получил `429 Too Many Requests`; до кода прогон при этом не дошёл
-  вовсе. Лечится перезапуском прогона, и от красного по существу отличается тем, на каком шаге
-  оно встало: три прогона одного дня упали именно так.
-- **Контекст `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, git-workflow-docker и git-workflow-secrets.
+description: Правило под «Закон о поставке» для дерева на GitLab. Брать на заведение задачи, ветки, коммит, пуш, создание MR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав MR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-pr, git-workflow-merge. Выкатка, образы и миграции — правило deploy-flow.
 ---
 
 # Поставка — как это устроено здесь
@@ -12,6 +12,9 @@ description: Правило под «Закон о поставке» для д
 учётная запись машинной работы и области коммита — при этом дереве, в `implementation.md`
 рядом: их не угадать, и общими они не бывают.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 | В законе                         | Здесь                                                                                                                                                                                                 |
@@ -23,9 +26,6 @@ description: Правило под «Закон о поставке» для д
 | состояние задачи в очереди работ | список доски, за которым стоит метка: заведённая, взятая в работу, ждущая разбора. Имена меток — в `implementation.md`; закрытая задача уходит из очереди слиянием, а не переносом в последний список |
 | PR о задаче                      | заголовок MR `[<КЛЮЧ>-<номер>] <Что сделано>` — тот же номер, что у задачи, и её название, переведённое в сделанное; тип и область коммита сюда не идут                                               |
 | обсуждение правки                | разбор MR: ревьювер — владелец проекта, исполнитель — учётная запись машинной работы, метки — те же, что у задачи                                                                                     |
-| попадание правки в главную ветку | слияние MR; оно же запускает выкатку — `.gitlab-ci.yml`                                                                                                                                               |
-| образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                              |
-| изменение хранилища              | миграция в `prisma/migrations/<метка>_<имя>/`                                                                                                                                                         |
 | запись о правке                  | коммит формата `type(scope): description` — типы `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`, `perf`; области — в `implementation.md`                                                 |
 | автор машинной работы            | отдельная учётная запись; её имя и место токена — в `implementation.md`. Токен лежит вне репозитория                                                                                                  |
 
@@ -130,12 +130,6 @@ flowchart TD
   остаётся в ней после слияния навсегда. Здесь она заводится проще, чем где-либо: доска
   собирается по меткам, и метка списка, поставленная на MR, тут же делает его карточкой.
   Находит такие сверка очереди — строкой на каждую.
-- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
-  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
-  не поднимает стенда, не снимает кадров и не собирает образов. Правила `rules:changes` считают
-  это сами, но по путям, а не по составу правки — совпадение пути ещё не значит, что задета
-  сборка, поэтому признак объявляется явно и один раз. Пропущенный шаг виден в прогоне
-  пропущенным — молча выпавший читается как пройденный.
 - **Отставший список находится сверкой очереди, а не глазами.** Сверка судит список по PR
   в обе стороны: открытый MR при задаче не в разборе и разбор без открытого MR — оба
   расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на доске нет.
@@ -147,37 +141,6 @@ flowchart TD
   исполнитель открывает карточку раньше, чем замысел эпика, а планирует по замыслу. Одна пометка без
   другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
   законно не делится: пометка объёма правом делить не становится.
-- **Слияние в главную ветку выкатывает прод.** Правила `only`/`rules` конвейера покрывают
-  документы отдельно, поэтому переменные окружения, секреты и записи имён ставятся до слияния,
-  а не после.
-- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
-  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
-  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
-  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
-- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
-  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
-- **Выкатка убирает за собой старые образы, оставляя три последних sha.** Помеченный sha образ
-  висячим не бывает никогда, и чистка висячего его не касается: за полгода они съедают диск
-  сервера целиком. Три sha — это глубина отката, и меньше брать нельзя: поломка, замеченная
-  через две выкатки, откатывается уже некуда.
-- **Описание прода правится вместе с составом прода.** Устройство, путь запроса, гейты и
-  бэкапы описаны текстами вне слоёв правил, и ни линтер, ни сборка их не читают: расхождение
-  копится молча, а читают эти тексты как действующие. Пару стережёт гард документов.
-- **Правка конвейера прогоняется до слияния ручным запуском.** Конвейер запускается на любой
-  ветке, а задание выкатки прибито правилом к главной: прогон ради проверки доходит до сборок и
-  там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
-  а не файл конвейера, — верность самого файла читается только по списку конвейеров после
-  пуша, и синтаксис отдельно судит проверка `.gitlab-ci.yml` в проекте.
-- **PR проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
-  образов идут на конвейере запроса слияния, выкатка — нет: её держит правило по главной ветке
-  у своего задания, а образ PR в реестр не уезжает.
-- **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
-  слиянием, но слияние — ещё не прод: отказавшая выкатка не трогает ни задачу, ни её список, и
-  заметить её неоткуда. Сверка спрашивает последний конвейер главной ветки и судит только
-  завершённый: идущий ещё может кончиться выкаткой.
-- **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
-  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
-  ветки, начатой раньше, встаёт перед той, от которой зависит.
 - **Документ едет в том же коммите, что и правка.** Обход — строка `Docs-skip: <причина>` в
   теле коммита; пустая причина не принимается.
 - **Заголовок коммита сверяется с форматом на месте.** Разобранный по типу и области
@@ -222,10 +185,6 @@ flowchart TD
   репозитории сценария наследует общий конфиг: если включена подпись, git идёт в агент ключей,
   а заблокированный агент роняет весь набор — со стороны это выглядит сломанным гардом. Автор,
   почта и подпись передаются флагами `-c` прямо в команду.
-- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
-  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
-  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
-  двух местах разное.
 
 ## Чего из закона здесь нет
 
@@ -248,52 +207,6 @@ flowchart TD
 
 ## Паттерны
 
-- `git-workflow-commit` — задача, ветка, коммит, пуш и MR от учётной записи машинной работы.
+- `git-workflow-commit` — задача, ветка, коммит и пуш от учётной записи машинной работы.
+- `git-workflow-pr` — открытие MR, черновик и его снятие, описание, ревьювер, метки, состояние.
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
-- `git-workflow-migration` — правка схемы хранилища и её миграций.
-- `git-workflow-restart` — ручной перезапуск прода.
-- `git-workflow-docker` — образы на своей машине: демон, реестр, сборка под платформу сервера.
-- `git-workflow-secrets` — ключи внешних служб: где лежат, как заводятся, что говорит их состояние.
-
-## Ловушки
-
-- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
-  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
-  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
-  закрывать два MR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
-  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
-- **Задача заводится командой, а не вызовами подряд.** Доска показывает те issue, чью метку
-  знает, и задача без метки списка в очереди работ не видна: со стороны это выглядит так же, как
-  незаведённая. Команда заведения ставит всё разом — issue, номер в его заголовке, метку списка,
-  исполнителя, — и печатает готовую строку заведения ветки. Замеченный по ходу дефект проходит
-  тот же путь.
-- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
-  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
-- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
-  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
-  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
-  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
-- **Учётная запись для пуша и автор MR выбираются отдельно.** Если пушить пришлось из-под другой
-  записи, на следующий вызов это не переносится: MR открывают токеном учётной записи машинной
-  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
-  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
-- **Невалидный файл конвейера виден отказом сразу после пуша, а не упавшим заданием.** Конвейер
-  на такой файл не заводится вовсе: в списке стоит запись об ошибке разбора, а внутри нет ни
-  задания, ни лога. Поэтому список конвейеров ветки смотрится тем же движением, что и пуш —
-  `glab ci list --branch <ветка>`, — а сам файл до пуша судит проверка `.gitlab-ci.yml` в
-  проекте.
-- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
-  конвейер.** Две стороны сходятся отдельно: `tags` у заданий и теги самого раннера. Пока
-  пересечения нет, раннер стоит `online` и не берёт ничего, а задания ждут общего раннера — по
-  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
-  не строку состояния.
-- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
-  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
-  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
-  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
-  `git-workflow-docker`.
-- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
-  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
-  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
-  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
-  список пополняется тем же движением, которым заводится новый файл вне индекса.