@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/rules/doc-style.md

@@ -2,33 +2,55 @@
 name: doc-style
 kind: rule
 law: project-documentation
-description: Правило под закон «Документация проекта». Брать при правке любого документа, включая спеки, а также комментариев в коде, тел коммитов и описаний PR. Пути, которые существуют, пара «правка и её документ», словарь проекта, запрет упоминать чужие проекты. Готовые формулировки — в паттерне doc-style-write. Чем это названо здесь — в implementation.md рядом.
+description: Правило под «Закон о документации проекта». Брать при правке любого .md, включая спеки, а также комментариев в коде, тел коммитов и описаний PR. Называет проверку путей, пары «правка и её документ» и то, что в этом дереве не проверяет ничто. Готовые формулировки — в паттерне doc-style-write.
 ---
 
-# Тексты проекта — каким приёмом
+# Тексты проекта — как это устроено здесь
 
-Правило под закон `{{lawsDir}}/project-documentation.md`. Закон говорит, что должно быть верно
-про тексты; здесь — каким приёмом это держится и что остаётся за автором. Где лежит словарь,
-чем проверяются пути и какие пары требует гейт — `implementation.md` рядом. Устройство спеков и
-слоёв документации — правило `spec-driven` под тем же законом.
+Правило под закон `docs/constitution/project-documentation.md`. Закон говорит, что должно
+быть верно про тексты; здесь — чем это проверяется в этом дереве и что остаётся за автором.
+Устройство спеков и слоёв документации — правило `spec-driven` под тем же законом; здесь
+только формулировки.
 
-## Когда берётся
+## Как это называется здесь
 
-Правка любого документа, комментария в коде, тела коммита, описания PR.
+| В законе                           | Здесь                                                                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| документ                           | любой `.md` вне `docs/archive/`, плюс комментарии в коде, тела коммитов и описания PR                              |
+| путь, названный в документе        | строка с расширением в обратных кавычках — её и ищет проверка                                                      |
+| правка, которую документ описывает | пара из `docs-guard`: правило и его зеркало, `.proto` и спек, хук и его сценарии, переезд файла и README обеих либ |
+| описание прошлого                  | `docs/archive/` — из проверки путей выведено целиком                                                               |
 
-## Что здесь действует
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
 
 - **Путь, названный в документе, существует.** Ссылка на переехавший файл читается как
-  действующее указание, и следующий читатель заводит снятое заново.
-- **Описание прошлого из проверки путей выведено целиком.** Архив по устройству называет файлы,
-  которых уже нет, и правкой это не лечится.
-- **Документ едет в том же коммите, что и правка, которую он описывает.** Обход — отметка с
-  причиной в теле коммита; пустая причина не принимается.
-- **Термин берётся из словаря проекта, а не придумывается на месте.** Слова, которого там нет,
-  у читателя нет тоже. Новое слово либо заводится в словаре вместе с правкой, либо заменяется
-  тем, что уже есть.
-- **Чужие проекты не упоминаются нигде** — ни имени репозитория, ни «портировано из», ни ссылок
-  на его файлы. Описывается то, что код делает здесь, в терминах этого проекта.
+  действующее указание, и следующий читатель заводит снятое заново. Судятся документы,
+  которые едут в репозиторий: личный черновик, закрытый `.gitignore` или
+  `.git/info/exclude`, проверка не читает — мёртвая ссылка в нём держала гейт пуша, хотя ни
+  в одну ветку этот файл не попадёт.
+- **Описание прошлого из проверки путей выведено целиком.** Архив по устройству называет
+  файлы, которых уже нет, и правкой это не лечится.
+- **Документ едет в том же коммите, что и правка, которую он описывает.** Обход — строка
+  `Docs-skip: <причина>` в теле коммита; пустая причина не принимается.
+
+## Чего из закона здесь нет
+
+Ни одна из формулировочных договорённостей не проверяется: одна фраза на правило, простые
+слова, отсутствие утверждений о будущем, свежесть числа в тексте. Две последние закон прямо
+оставляет автору: открытый вопрос пишется теми же словами, что и обещание, а дата и номер —
+такие же числа, как то, что пересчитывают.
+
+На комментарии в коде правило распространяется, но гейтом не требуется: он зовёт его только
+на `.md`. Расширять требование на каждый `.ts` значило бы шуметь на каждой правке, поэтому
+здесь оно держится памятью автора — и цена этого видна: слова из левой колонки словаря живут
+в комментариях хуков и `tools/*.mjs` десятками строк, включая текст отказа, который гард
+печатает агенту.
 
 ## Паттерны
 
@@ -37,25 +59,59 @@ description: Правило под закон «Документация про
 
 ## Ловушки
 
-- **Оставшаяся работа не записывается в документ, а заводится задачей.** «Сделать потом» в
-  плане, README или спеке — второй список работ: он расходится с очередью задач молча, а
-  разбирать его потом дороже, чем завести задачу сразу. Документ держит только то, что задачей
-  не бывает: договорённости и решения, которые решено не править.
-- **Словарь действует и на разговор с владельцем, не только на файлы.** Слово, от которого в
-  дереве отказались, всплывает именно в отчёте о сделанном — и владелец читает ровно то слово,
-  которое просил не употреблять.
+- **Оставшаяся работа не записывается в документ, а заводится задачей.** `docs/BACKLOG.md`
+  держит только то, что задачей не бывает: договорённости и решения, которые решено не
+  править. Признак — утверждение остаётся, если править его никто не собирается. «Сделать
+  потом» в плане, README или спеке — второй список работ: он расходится с бордой молча, а
+  разбирать его потом дороже, чем завести задачу сразу. Из 1411 строк документа действующими
+  оказались 71, и на разбор остальных ушла отдельная задача. Как разбирать накопившееся —
+  паттерн `doc-style-sweep`.
+- **Словарь действует и на разговор с владельцем, не только на файлы.** Он приходит в контекст
+  на запуске сессии, поэтому «не читал» основанием не бывает. Слово из левой колонки «Так не
+  пишем» всплывало именно в ответах: в дереве его уже вычистили, а в отчёте о сделанном оно
+  оставалось, и владелец читал ровно то слово, от которого отказались.
+- **Термин берётся из `docs/GLOSSARY.md`, а не придумывается на месте.** Слова, которого там
+  нет, у читателя нет тоже: «журнал приложения» простоял в спеке почты, пока владелец не
+  спросил, что это, — оказалось, логи бэкенда, а слово «журнал» здесь уже занято журналом
+  событий. Новое слово либо заводится в словаре вместе с правкой, либо заменяется тем, что
+  уже есть.
 - **Проход по словарю глазами слово не находит.** «Формулировки приведены к словарю» означает
-  ровно те строки, которые в тот момент читали. Снятое слово вычищается поиском по всему дереву,
-  а не вычиткой; ищутся сочетания, а не корень — совпадений по корню законных обычно больше,
-  чем нарушений.
-- **Снятое имя вычищается одним проходом по всему дереву:** правила, их зеркала, документы и
-  комментарии. Описание того, чего в коде уже нет, читается как действующее указание.
-- **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет внутри
-  одной ветки. Число, которое придётся пересчитывать при каждой правке, лучше не писать вовсе;
-  число, полученное разбором текста, сверяется на выборке руками — разбор, не знающий второй
-  формы записи, ошибается молча.
+  ровно те строки, которые в тот момент читали: «спека» пережила такой проход и осталась в
+  соседней строке того же файла. Слово из левой колонки таблицы «Так не пишем» вычищается
+  грепом по всему дереву, а не вычиткой. Форма задаётся точно: «спек» — документ — склоняется
+  в «спека» и «спеки» тоже, и совпадений по корню законных больше, чем нарушений; ищутся
+  сочетания («спеки на … нет», «спека проверяет»), а не корень.
+- **Снятое имя вычищается одним грепом по всему дереву:** правила, их зеркала в скилах,
+  документы и комментарии. Описание того, чего в коде уже нет, читается как действующее
+  указание.
+- **Поиск по дереву не покрывает того, что уже уехало наружу.** Заголовок задачи и её тело,
+  заголовок отчёта и его тело, заголовки коммитов лежат вне файлов, и проверки текстов их не
+  читают вовсе. Вычистив слово в дереве, обходят те же места в очереди работ и в истории:
+
+    ```bash
+    <клиент хостинга> api "<путь к отчёту>" --jq '.title, .body' | grep -i '<слово>'
+    <клиент хостинга> api "<путь к задаче>" --jq '.title, .body' | grep -i '<слово>'
+    git log --format='%s%n%b' <база>..HEAD | grep -i '<слово>'
+    ```
+
+    Заголовок отчёта правится вызовом хостинга, заголовок коммита — только переписыванием ветки,
+    поэтому его проверяют до пуша. Выдуманное слово было вычищено из трёх файлов и объявлено
+    снятым, а в заголовке отчёта и в заголовке коммита осталось — владелец прочитал именно его.
+
+- **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет
+  внутри одной ветки: «шестнадцать пар» стало неправдой через два коммита после того, как
+  было написано, и нашёл это владелец, а не проверка. Число, которое придётся пересчитывать
+  при каждой правке, лучше не писать вовсе. Число, полученное разбором текста, сверяется на
+  выборке руками до того, как его называют: разбор, не знающий второй формы записи, ошибается
+  молча — «51 пункт без задачи» оказался шестью, потому что номер стоял и отдельной строкой, и
+  в заголовке подраздела.
 - **Сделанность читается по дереву, а не по тексту, который о ней написан.** Это верно в обе
-  стороны: вычеркнутый пункт при несделанной работе и несделанным названная задача, закрытая
-  наполовину, встречаются одинаково часто. Пункт плана описывает день, когда его написали.
-- **Комментарий в файле — такое же утверждение, как строка в документе.** Выдуманное
-  обоснование живёт в коде годами и каждый раз читается как основание ничего не трогать.
+  стороны: строка про README обеих либ была вычеркнута как сделанная, а README остался с
+  прежним числом импортёров; задача, названная владельцу несделанной, оказалась наполовину
+  закрытой и покрытой сценариями хука. Пункт плана и тело задачи описывают день, когда их
+  написали, и с тех пор не менялись.
+- **Комментарий в файле — такое же утверждение, как строка в документе.** Обоснование «строки
+  идут во всю ширину панели, иначе подсветка обрывается» было выдумано, прожило три сессии и
+  каждый раз читалось как основание вёрстку не трогать.
+- **Чужие проекты не упоминаются нигде** — ни имени репозитория, ни «портировано из», ни
+  ссылок на его файлы. Описывается то, что код делает здесь, в терминах этого проекта.

package/assets/rules/entity-conventions.md

@@ -0,0 +1,78 @@
+---
+name: entity-conventions
+kind: rule
+law: entity-editing
+description: Правило под «Закон о правке сущности». Брать при правке любого стора админки (*.store.ts) и любой панели создания или правки записи. Называет общую основу асайда, общую основу списочного стора, устройство панели и то, что асайд открывается маршрутом в аутлете ro. Готовый код — в паттернах entity-aside и entity-store.
+---
+
+# Правка сущности — как это устроено здесь
+
+Правило под закон `docs/constitution/entity-editing.md`. Закон говорит, как ведёт себя
+приложение при создании и правке записи; здесь — из чего это собрано в этом дереве и как
+выглядит. Про вид говорит правило: закон о нём молчит намеренно.
+
+## Как это называется здесь
+
+| В законе                      | Здесь                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------ |
+| панель правки записи          | асайд; открывается маршрутом с `outlet: 'ro'`                            |
+| общая основа асайда           | `RtRouteAsideComponent<T>` — директива без селектора                     |
+| общая основа списочного стора | `BaseListStoreService`                                                   |
+| запись                        | `entity`, `entityId`, `isCreateMode` — имена от сущности, а не от домена |
+| обвязка записи                | `runMutation` в панели, `mutate` в сторе                                 |
+| нетронутость формы            | `pristineSignal(control)`                                                |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Асайд открывается маршрутом в аутлете `ro`, а не вызовом сервиса.** Программного открытия
+  через `RtAsideService.open()` в админке нет: так панель переживает перезагрузку, передаётся
+  ссылкой и попадает в историю браузера.
+- **Запись идёт через `runMutation`, и панель отдаёт основе поток мутации и ключи.** Занятость,
+  гашение прежней ошибки, тост об успехе и закрытие держит основа.
+- **Поток мутации обязан отдать значение или ошибку.** Пустой поток гасит панель навсегда:
+  она ждёт того или другого, а закрыть её владелец не может, пока идёт запись.
+- **Мутация завершается перечитанным списком, а не отправленным запросом.** Список,
+  перечитанный после закрытия, показал бы прежнее значение.
+- **Стор отвечает потоком: успех — значение, отказ — ошибка потока.** Булева ответа у сторов
+  админки не осталось: он терял и записанную запись, и причину отказа.
+- **Имена берутся от сущности, а не от домена.** `save`, `remove`, `load` — не
+  `createBooking`, `loadBookings`: имя домена уже в имени стора.
+- **Гард несохранённых правок ставит сама панель и на все четыре пути закрытия.** Проверять
+  один путь бессмысленно — Esc обойдёт то, что ловит кнопка. Четыре пути — кнопка в шапке,
+  кнопка в футере, нажатие мимо панели и Esc.
+- **Уход из панели идёт через `openRelated`, а не своим `router.navigate`.** Абсолютные
+  команды меняют только первичную ветку, аутлет `ro` остаётся в адресе, и роутер отклоняет
+  навигацию молча.
+- **Запись читается по идентификатору из адреса полной моделью, а не берётся из списка.**
+  Список отдаёт короткую.
+
+## Чего из закона здесь нет
+
+Чтение записи отдельной процедурой заведено не везде — долг `Q-M-3`. Файл стора называется
+`<сущность>.store.ts`; имя `<сущность>-store.service.ts` выводит его и из правила линтера, и
+из гейта скилов, и общие сторы заявок и объектов правятся без правил сущностей вовсе.
+
+## Паттерны
+
+- `entity-aside` — собрать панель правки: маршрут, основа, `runMutation`, шапка и футер, гард.
+- `entity-store` — собрать стор сущности: наследник общей основы, `mutate`, ключи отказа.
+
+## Ловушки
+
+- Действие со своей занятостью через основу не идёт: опрос подписки держит свой `pollingId`,
+  потому что панель на минуту опроса не гасится.
+- Хвост с `EMPTY`, приклеенный к мутации, гасится `defaultIfEmpty`: иначе отказ приклеенного
+  потока превращает удачную запись в вечный спиннер.
+- `routerLink` в панели не годится: директива навигирует сама, `preventDefault` её не
+  останавливает, и вопрос о несохранённых правках она обходит.
+- `viewChild` на поле с `#` Angular не принимает — поле объявляется `protected`.
+- Скелетоны полей идут по `resolving()`, не по `busy()`: `busy` включает и запись, и чтение.
+- Панель, которая после успеха остаётся открытой, сбрасывает нетронутость сама.
+- Ветка, куда забыли подмешать константу ro-маршрута, отличается только тем, что кнопка в
+  шапке на ней ничего не открывает: сборка, линт и маршруты остальных веток при этом целы.

package/assets/rules/entity-models.md

@@ -0,0 +1,70 @@
+---
+name: entity-models
+kind: rule
+law: entity-models
+description: Правило под «Закон о моделях сущностей». Брать при объявлении или правке модели записи и её маппера в админке, при правке моделей и мапперов в libs/common/util и при правке .proto. Называет неймспейс I<Сущность>, уровни модели и что берётся из @rt-tools/utils. Готовый код — в паттерне entity-models-new.
+---
+
+# Модели сущностей — как это устроено здесь
+
+Правило под закон `docs/constitution/entity-models.md`. Закон говорит, сколько данных
+приложение запрашивает на каждом экране; здесь — как эта модель объявляется в этом дереве.
+
+## Как это называется здесь
+
+| В законе                 | Здесь                                                                |
+| ------------------------ | -------------------------------------------------------------------- |
+| сторона контракта        | `Api` — псевдоним сгенерированного типа из `@<область>/common/proto` |
+| то, чем пользуется экран | `State`, все поля `readonly`                                         |
+| то, что уходит на запись | `Draft`                                                              |
+| короткий уровень         | вложенный неймспейс `Short` с собственными `Api` и `State`           |
+| перевод                  | маппер-наследник `BaseMapper`, свой на каждый уровень                |
+
+Все три стороны лежат в одном неймспейсе `I<Сущность>` и спутать их в импортах нечем.
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **У сущности две стороны, и обе лежат в неймспейсе `I<Сущность>`.** `Api` повторяет
+  контракт, `State` нормализован и от смены контракта не зависит.
+- **Сторона контракта руками не пишется — она объявляется псевдонимом.** Своя копия разойдётся
+  с контрактом молча, а компилируется из них только одна.
+- **Между сторонами стоит маппер-наследник `BaseMapper`, и экраны читают только `State`.** Тип
+  из контракта в шаблон не попадает.
+- **Пустое выражается пустой строкой или нулём, а не отсутствием поля.** Необязательных
+  скаляров в контракте нет, поэтому `null` и `undefined` в `State` не заводятся; смысл нуля
+  объясняется комментарием рядом с полем.
+- **Приведение идёт через `this.typeCast`, а не через `??`.** Контракт отдаёт значения по
+  умолчанию, а не пустоту, и проверка на `undefined` здесь не ловит ничего.
+- **Типы страницы, порядка и отбора берутся из `@rt-tools/utils`.** Второго набора этих типов
+  в дереве нет: `rt-pagination` принимает `IPageModel` оттуда же.
+
+## Чего из закона здесь нет
+
+Уровней нет ни у одной сущности, и контракт короткого сообщения не отдаёт — долги `Q-M-1` и
+`Q-M-2`. Новая сущность заводится сразу с уровнями.
+
+Правка `.proto` не проверяется ничем: `buf lint` и `buf breaking` настроены, но не входят ни в
+`check:all`, ни в CI.
+
+## Паттерны
+
+- `entity-models-new` — объявить модель и маппер: неймспейс, уровни, `typeCast`, перегенерация
+  контракта.
+
+## Ловушки
+
+- `getAsType` умолчания не принимает: значение вне набора он пишет в консоль и возвращает
+  строкой `'unknown'`. Строковое поле с конечным набором значений сверяется с набором явно.
+- `as Type` в маппере запрещено — правило `typescript-conventions`.
+- Поле-сообщение необязательно всегда; обязательное поле модели им не заполнить без запасного
+  значения. Обратно, в запрос, `readonly`-массив не проходит: init-тип требует изменяемый.
+- Модель админки и модель сайта — разные. Общий тип на два приложения означал бы, что сайт
+  тянет поля админки.
+- Снятое поле контракта помечается `reserved` с номером и именем: номер, отданный новому полю,
+  ломает уже выкаченного клиента молча.

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

@@ -0,0 +1,116 @@
+---
+name: git-workflow
+kind: rule
+law: delivery
+description: Правило под «Закон о поставке» для дерева в Azure DevOps. Брать на заведение задачи, ветки, коммит, пуш, создание PR, слияние, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет рабочий элемент как начало работы, его состояние как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration и git-workflow-restart.
+---
+
+# Поставка — как это устроено здесь
+
+Правило под закон `docs/constitution/delivery.md`. Закон говорит, что должно быть верно;
+здесь — каким приёмом это держится в дереве, лежащем в Azure DevOps. Организация, проект,
+учётная запись машинной работы и области коммита — при этом дереве, в `implementation.md`
+рядом: их не угадать, и общими они не бывают.
+
+## Как это называется здесь
+
+| В законе                         | Здесь                                                                                                                                                                                                                                  |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| главная ветка                    | `main`                                                                                                                                                                                                                                 |
+| отдельная ветка                  | `<номер рабочего элемента>-<короткий-slug>`; форма — в `implementation.md`. Имя без номера (`feat/…`, `fix/…`) законно, пока ветка живёт локально: PR с неё не откроется                                                               |
+| задача                           | рабочий элемент (work item) рода `Task` или `Bug`, заголовок `[<номер>] <Что не так>`, исполнитель — учётная запись машинной работы; PR прикрепляется к нему при создании флагом `--work-items`, а коммит — строкой `AB#<номер>`       |
+| очередь работ                    | Azure Boards проекта. Рабочий элемент попадает на доску тем, что заведён: доска показывает элементы своей области и итерации                                                                                                           |
+| состояние задачи в очереди работ | поле `State` рабочего элемента: `New` у заведённого, `Active` у взятого в работу, `Resolved` у ждущего разбора. Набор состояний зависит от процесса проекта и назван в `implementation.md`; закрытая задача уходит из очереди слиянием |
+| отчёт о задаче                   | заголовок 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`. Токен лежит вне репозитория                                                                                                                                   |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Коммит в главную ветку отбивается гардом.** Гард ищет вызов коммита в любом месте команды
+  и смотрит текущую ветку на момент запуска, поэтому составная «создать ветку и сразу
+  коммитить» отклоняется целиком: ветки в момент разбора ещё нет.
+- **Ветка без номера рабочего элемента PR не открывает.** Гард поставки отбивает
+  `az repos pr create` с такой ветки: локально она законна, но правка из неё — это выкатка, за
+  которой в очереди работ ничего не стоит. Заводится рабочий элемент, и работа переносится в
+  ветку с его номером.
+- **Номер ветки и номер в заголовке PR сверяются на месте, а состояние — по доске.** Формат
+  читается из текста команды и работает без сети; существование рабочего элемента, его
+  состояние, исполнитель и то, что он ещё открыт, — только когда есть чем спросить. Нет сети
+  или нет токена — второй ярус молча пропускается: проверка, падающая в самолёте, перестаёт
+  что-либо значить.
+- **Состояние рабочего элемента двигается тем же движением, что и работа.** Ветка заведена —
+  элемент переводится в `Active`, PR открыт — в `Resolved`; делает это команда перевода, а не
+  набор вызовов по памяти. Перевод идёт сразу за шагом, который его вызвал: очередь работ
+  читают между шагами, а не после них.
+- **Отставшее состояние находится сверкой очереди, а не глазами.** Сверка судит состояние по
+  отчёту в обе стороны: открытый PR при элементе не в разборе и разбор без открытого PR — оба
+  расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на доске нет.
+- **Задачи, чинящиеся одной правкой, сливаются до слияния ветки.** Вторая закрывается как
+  дубликат, а недостающее из неё дописывается в первую. После слияния слить уже нельзя: ветка
+  въехала, и откатывается она целиком.
+- **Слияние в главную ветку выкатывает прод.** Фильтры путей конвейера покрывают документы
+  отдельно, поэтому переменные окружения, секреты и записи имён ставятся до слияния, а не
+  после.
+- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
+  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
+  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
+  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
+- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
+  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Цепочка миграций прогоняется с пустого хранилища до слияния.** Порядок применения
+  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит.
+- **Документ едет в том же коммите, что и правка.** Обход — строка `Docs-skip: <причина>` в
+  теле коммита; пустая причина не принимается.
+- **Заголовок коммита сверяется с форматом на месте.** Разобранный по типу и области
+  заголовок читается списком, а свободный текст — только целиком.
+- **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы
+  стилей вовсе, и правила оформления без второго прогона не проверяет ничто.
+- **Рабочий элемент привязывается к PR при создании, а не после.** `az repos pr create`
+  принимает `--work-items`; привязка второй командой обходится молча, когда у токена нет права
+  править чужой элемент, и PR остаётся ни с чем не связанным.
+- **Слияние с автозавершением не заменяет проверок до пуша.** Автозавершение видит только
+  конвейер, а конвейер видит только отправленное: красная ветка занимает очередь работ и
+  выглядит готовой к разбору.
+- **Набор состояний берётся у процесса проекта, а не назначается правилом.** Agile, Scrum и
+  Basic называют одни и те же три шага по-разному, и перевод в состояние, которого в процессе
+  нет, отвечает отказом на каждой задаче подряд.
+- **Сценарии гардов задают настройки git сами, а не берут их с машины.** Коммит во временном
+  репозитории сценария наследует общий конфиг: если включена подпись, git идёт в агент ключей,
+  а заблокированный агент роняет весь набор — со стороны это выглядит сломанным гардом. Автор,
+  почта и подпись передаются флагами `-c` прямо в команду.
+- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
+  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
+  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
+  двух местах разное.
+
+## Чего из закона здесь нет
+
+Гард поставки стоит на командах агента, поэтому ветку, заведённую руками в редакторе, он не
+видит: имя такой ветки держится памятью. Требование от этого не слабеет — просто отдельной
+проверки под него не заводится: работа опознаётся заголовком рабочего элемента и отчёта, а это
+сверяется у всех. Сверка очереди имя ветки не судит вовсе: у открытого PR его не переименовать.
+
+Взятие задачи в работу не стережёт ничто: доска ветки не видит, а гард поставки её видит, но
+доску не правит — сетевой вызов в разборе команды падал бы вместе со связью и отбивал бы
+работу вместо промаха. Держится это памятью и подсказкой, которую печатает команда заведения
+задачи. Отставшее состояние находит сверка очереди — но уже после того, как PR открыт.
+
+## Паттерны
+
+- `git-workflow-commit` — рабочий элемент, ветка, коммит, пуш и PR от учётной записи машинной
+  работы.
+- `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
+- `git-workflow-migration` — правка схемы хранилища и её миграций.
+- `git-workflow-restart` — ручной перезапуск прода.

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

@@ -0,0 +1,123 @@
+---
+name: git-workflow
+kind: rule
+law: delivery
+description: Правило под «Закон о поставке» для дерева на GitHub. Брать на заведение задачи, ветки, коммит, пуш, создание PR, мерж, а также на правку схемы хранилища, её миграций и вызовы миграций. Называет задачу на борде как начало работы, колонку задачи как ход работы, соответствие задачи и ветки один к одному, имя ветки, формат коммита, учётную запись машинной работы, обязательный состав PR, гарды поставки и сверку очереди работ. Готовый код — в паттернах git-workflow-commit, git-workflow-merge, git-workflow-migration и git-workflow-restart.
+---
+
+# Поставка — как это устроено здесь
+
+Правило под закон `docs/constitution/delivery.md`. Закон говорит, что должно быть верно;
+здесь — каким приёмом это держится в дереве, лежащем на GitHub. Ключ задач, адрес борды,
+учётная запись машинной работы и области коммита — при этом дереве, в `implementation.md`
+рядом: их не угадать, и общими они не бывают.
+
+## Как это называется здесь
+
+| В законе                         | Здесь                                                                                                                                                                                           |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| главная ветка                    | `main`                                                                                                                                                                                          |
+| ключ задач                       | короткое слово, которым дерево зовёт свои задачи; задаётся ключом `board.taskKey` в `.claude/rt-kit/checks.json`, а в `implementation.md` называется для читателя                               |
+| отдельная ветка                  | `<КЛЮЧ>-<номер задачи>-<короткий-slug>`. Имя без номера (`feat/…`, `fix/…`) законно, пока ветка живёт локально: PR с неё не откроется                                                           |
+| задача                           | issue репозитория, заголовок `[<КЛЮЧ>-<номер>] <Что не так>`, исполнитель — учётная запись машинной работы; PR прикрепляется к нему строкой `Closes #<номер>` в теле                            |
+| очередь работ                    | борда GitHub Projects. К репозиторию она не привязана: `projectsV2` у него пуст, и задача попадает на борду только явным добавлением                                                            |
+| состояние задачи в очереди работ | колонка борды — поле «Status»: заведённая, взятая в работу, ждущая разбора. Имена колонок — в `implementation.md`; закрытая задача уходит из очереди мержем, а не переводом в последнюю колонку |
+| отчёт о задаче                   | заголовок 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`. Токен лежит вне репозитория                                                                                            |
+
+## Где это лежит
+
+В этом дереве — таблица в `implementation.md` рядом. Пути живут там, а не здесь: правило
+переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
+же дереве, которое держит код иначе.
+
+## Как закон применяется здесь
+
+- **Коммит в главную ветку отбивается гардом.** Гард ищет вызов коммита в любом месте команды
+  и смотрит текущую ветку на момент запуска, поэтому составная «создать ветку и сразу
+  коммитить» отклоняется целиком: ветки в момент разбора ещё нет.
+- **Ветка без номера задачи PR не открывает.** Гард поставки отбивает `gh pr create` с такой
+  ветки: локально она законна, но правка из неё — это выкатка, за которой в очереди работ
+  ничего не стоит. Заводится задача, и работа переносится в ветку с её номером.
+- **Ключ задач задаётся один раз, и все три формы имени выводятся из него.** Заголовок задачи,
+  имя ветки и заголовок отчёта строит один и тот же ключ: команда заведения задачи собирает по
+  нему заголовок, гард поставки достаёт по нему номер из имени ветки, сверка очереди — из
+  заголовка. Форма ветки в профиле дерева пишется той же парой `<КЛЮЧ>-<номер>`, а не своей
+  похожей: разойдясь, они не отказывают, а перестают узнавать номер, и проверка, искавшая
+  работу без задачи, пропускает всё подряд.
+- **Незаданный ключ отбивает работу с очередью на месте.** Модуль борды отказывает при первом
+  же вызове и называет, где ключ задаётся. Умолчания у ключа нет намеренно: собранный из
+  пустого значения заголовок `[-317]` не совпадает ни с чем, и сверка очереди помечает
+  неправильно названной каждую задачу — настоящее расхождение тонет среди этих строк.
+- **Номер ветки и номер в заголовке PR сверяются на месте, а состояние задачи — по борде.**
+  Формат читается из текста команды и работает без сети; существование задачи, её присутствие
+  на борде, исполнитель и то, что она ещё открыта, — только когда есть чем спросить. Нет сети
+  или нет токена — второй ярус молча пропускается: проверка, падающая в самолёте, перестаёт
+  что-либо значить.
+- **Колонка задачи двигается тем же движением, что и работа.** Ветка заведена — задача
+  переставляется во взятые в работу, PR открыт — в ждущие разбора; делает это команда
+  перевода, а не набор вызовов GraphQL по памяти. Перевод идёт сразу за шагом, который его
+  вызвал: очередь работ читают между шагами, а не после них.
+- **Отставшая колонка находится сверкой очереди, а не глазами.** Сверка судит колонку по
+  отчёту в обе стороны: открытый PR при задаче не в разборе и разбор без открытого PR — оба
+  расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на борде нет.
+- **Задачи, чинящиеся одной правкой, сливаются до мержа.** Вторая стирается вместе с номером,
+  а недостающее из неё дописывается в первую. После мержа слить уже нельзя: ветка въехала, и
+  откатывается она целиком.
+- **Мерж в главную ветку выкатывает прод.** Исключения по путям покрывают только документы,
+  поэтому переменные окружения, секреты и записи имён ставятся до мержа, а не после.
+- **Признак режима объявлен в образе, а не только в составе прода.** Значение, заданное
+  составом, действует лишь на контейнер, поднятый этим составом; ручной прогон того же образа
+  идёт с пустым значением, а пусто здесь означает локалхост — со всеми отладочными
+  умолчаниями, которые он разрешает. Умолчание образа задаётся в самом образе.
+- **Образы выкатываются по sha коммита, а не по метке «последний».** Метка в реестре отстаёт
+  от главной ветки, и прод молча возвращается к прежней версии, продолжая отвечать.
+- **Цепочка миграций прогоняется с пустого хранилища до мержа.** Порядок применения
+  лексикографический по имени каталога, а метку времени ставит момент создания: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит.
+- **Документ едет в том же коммите, что и правка.** Обход — строка `Docs-skip: <причина>` в
+  теле коммита; пустая причина не принимается.
+- **Заголовок коммита сверяется с форматом на месте.** Разобранный по типу и области
+  заголовок читается списком, а свободный текст — только целиком.
+- **Перед пушем прогоняются все линтеры, а не один.** Линтер кода обычно не читает файлы
+  стилей вовсе, и правила оформления без второго прогона не проверяет ничто.
+- **Автор PR не может быть его ревьювером.** Запрос разбора на самого себя GitHub принимает и
+  молча не создаёт — разбор при этом выглядит запрошенным.
+- **Метки, исполнитель и ревьювер PR ставятся вызовами `gh api`, а не `gh pr edit`.** На
+  репозитории со старой бордой `gh pr edit` отвечает отказом про Projects (classic) и до
+  правки не доходит вовсе.
+- **Борда правится запросом GraphQL по идентификатору проекта.** `gh project` с `--owner`
+  отвечает `unknown owner type`, когда владелец борды — не та учётная запись, под которой
+  идёт вызов.
+- **Сценарии гардов задают настройки git сами, а не берут их с машины.** Коммит во временном
+  репозитории сценария наследует общий конфиг: если включена подпись, git идёт в агент ключей,
+  а заблокированный агент роняет весь набор — со стороны это выглядит сломанным гардом. Автор,
+  почта и подпись передаются флагами `-c` прямо в команду.
+- **Расхождение миграций со схемой меряется на теневом хранилище, а не на том, где работает
+  тот, кто пушит.** Оно законно несёт след любой недоделанной ветки, и сверка с ним держала бы
+  чужую правку. Гейт и выкатка зовут одну и ту же проверку — иначе «сошлось» станет значить в
+  двух местах разное.
+
+## Чего из закона здесь нет
+
+Гард поставки стоит на командах агента, поэтому ветку, заведённую руками в редакторе, он не
+видит: имя такой ветки держится памятью. Требование от этого не слабеет — просто отдельной
+проверки под него не заводится: работа опознаётся заголовком задачи и отчёта, а это сверяется
+у всех. Сверка очереди имя ветки не судит вовсе: у открытого PR его не переименовать.
+
+Взятие задачи в работу не стережёт ничто: борда ветки не видит, а гард поставки её видит, но
+борду не правит — сетевой вызов в разборе команды падал бы вместе со связью и отбивал бы
+работу вместо промаха. Держится это памятью и подсказкой, которую печатает команда заведения
+задачи. Отставшую колонку находит сверка очереди — но уже после того, как PR открыт.
+
+## Паттерны
+
+- `git-workflow-commit` — задача, ветка, коммит, пуш и PR от учётной записи машинной работы.
+- `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
+- `git-workflow-migration` — правка схемы хранилища и её миграций.
+- `git-workflow-restart` — ручной перезапуск прода.