@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/patterns/git-workflow-commit.github.md

@@ -0,0 +1,337 @@
+---
+name: git-workflow-commit
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит, пуш и создание PR — готовая команда заведения задачи со всеми четырьмя шагами, перевод задачи в колонку работы и в колонку разбора, слияние двух задач в одну, сверка очереди работ, работа от учётной записи бота, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки PR, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+---
+
+# Ветка, коммит и PR
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Заводится задача, с которой начинается правка.
+- Заводится ветка под задачу.
+- Готовится коммит или пуш.
+- Открывается PR.
+- Работа перешла на следующий шаг, и задача переставляется в другую колонку борды.
+
+## Сначала задача на борде, потом ветка
+
+Заведение состоит из четырёх шагов: issue, номер в его заголовке, добавление на борду,
+первая колонка. Борда к репозиторию не привязана — `projectsV2` у него пуст, — поэтому третий
+шаг сам не случается, и задача без него не видна ни в очереди работ, ни владельцу: так две
+задачи и простояли месяц.
+
+Все четыре шага делает одна команда дерева, а не рука: делить их значит забывать третий.
+
+```bash
+npm run task:new -- --title 'Письма владельцу не уходят молча' \
+    --label bug --label area:api --slug mail-owner-silence < описание.md
+```
+
+Тело читается со стандартного ввода, `--slug` необязателен и идёт только в подсказку с именем
+ветки. Автор и исполнитель — учётная запись машинной работы; токен команда читает сама, из
+файла вне репозитория.
+
+Скрипт под этой командой заводит проект — пакет её не везёт. Что он делает вызовами `gh`:
+
+```bash
+gh issue create --title '[<КЛЮЧ>-<номер>] …' --label bug --assignee <бот> --body-file -
+gh issue edit <номер> --title '[<КЛЮЧ>-<номер>] …'   # номер известен только после создания
+gh project item-add <номер борды> --owner <владелец> --url <адрес issue>
+```
+
+Последний шаг и есть тот, который забывается: без него задача заведена, но её нет в очереди.
+
+Название тикета говорит, что не так, а не что сделать: PR потом переводит его в сделанное.
+Номер в заголовок руками не пишется — он известен только после создания, и команда дописывает
+его сама.
+
+Чем сверить, что очередь работ в порядке:
+
+```bash
+npm run check:board
+```
+
+Она смотрит только открытое: тикеты на борде, номер и исполнителя у каждой открытой задачи,
+а у каждого открытого PR — номер в заголовке, строку `Closes`, открытую задачу за ним и то,
+что второго PR с тем же номером нет. Имя ветки не судит: у открытого PR его не переименовать.
+
+Закрытые задачи сверка на борде не ищет, и добавлять их туда задним числом не надо: закрытая
+задача уходит из очереди мержем, а колонки под неё у борды нет. О закрытой задаче сверка
+помнит только одно — её папку в `docs/tasks/`.
+
+## Две задачи, которые чинятся одной правкой
+
+Если по ходу выяснилось, что правка закрывает и соседнюю задачу, — это одна задача, а не две.
+Слить их можно, пока правка не въехала в главную ветку:
+
+```bash
+GH=/opt/homebrew/bin/gh
+# то, чего в поглотившей задаче не было, дописывается в её тело
+$GH api -X PATCH repos/<владелец>/<репозиторий>/issues/<поглотившая> -f body="$(cat тело.md)"
+# поглощённая стирается вместе с номером — две строки об одной работе хуже дыры в нумерации
+$GH api graphql -f query='mutation { deleteIssue(input: {issueId: "<node-id>"})
+    { repository { name } } }'
+```
+
+Удаление необратимо и уносит с собой ссылки вида `Closes #<номер>` из чужих тел — поэтому
+сначала правится поглотившая задача, и только потом стирается поглощённая. После мержа
+поглощения нет: ветка въехала, и откатывается она целиком.
+
+## Ветка заводится отдельным вызовом
+
+Гард главной ветки разбирает текст команды и смотрит ветку на момент запуска, поэтому
+составная команда отклоняется целиком — ветки в ней ещё нет:
+
+```bash
+✗ git checkout -b <КЛЮЧ>-85-guest-token && git commit -m 'feat(admin): …'
+✓ git checkout -b <КЛЮЧ>-85-guest-token
+✓ git commit -F -
+```
+
+Имя — `<КЛЮЧ>-<номер задачи>-<короткий-slug>`, slug строчными латинскими через дефис. Гард
+поставки разбирает его на месте и отбивает промах в форме до первого коммита, а по номеру
+спрашивает борду: задача должна существовать, быть открытой, стоять в очереди и иметь
+исполнителя.
+
+Имя без номера (`feat/…`, `fix/…`) законно, пока ветка живёт локально — под пробу и разбор.
+PR с неё не откроется: правка, доезжающая до главной ветки, начинается с задачи.
+
+## Колонка задачи двигается вместе с работой
+
+Ветка заведена — задача уже не в `📋 Backlog`, а в работе. PR открыт — она ждёт разбора.
+Оба перевода делает одна команда, вторым вызовом сразу за тем, который его вызвал:
+
+```bash
+npm run task:move -- 86 in-progress   # сразу после git checkout -b <КЛЮЧ>-86-…
+npm run task:move -- 86 in-review     # сразу после gh pr create
+```
+
+Колонки под своими именами: `backlog`, `in-progress`, `in-review`, а ещё `new`, `ready`,
+`done` и `deployed`, через которые работа не проходит — закрытая задача уходит из очереди
+мержем. Команда правит борду под ботом, читает токен сама и печатает, откуда куда переставила;
+задачи не на борде и незнакомой колонки не принимает.
+
+Перевод не откладывается на потом: очередь работ читают между шагами, а не после них. Задача
+с открытым PR простояла в `📋 Backlog` до самой сверки — всё это время она выглядела
+нетронутой, а разбора за неё никто не ждал.
+
+## Коммит подписывается ботом
+
+Токен читается в переменную и не печатается; автор и коммиттер задаются переменными той же
+команды. `git config` не годится — конфиг общий с основным деревом и переписал бы подпись
+владельцу:
+
+```bash
+TOKEN=$(tr -d '\n' < ~/.config/<дерево>-bot-token)
+
+GIT_AUTHOR_NAME="<бот>" GIT_AUTHOR_EMAIL="<номер>+<бот>@users.noreply.github.com" \
+GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<номер>+<бот>@users.noreply.github.com" \
+    git commit -F -
+```
+
+Заголовок — `type(scope): description`. Типы: `feat`, `fix`, `refactor`, `docs`, `style`,
+`test`, `chore`, `perf`. Области: `site`, `admin`, `api`, `common`, `proto`, `deploy`. Точка в
+конце заголовка не принимается, длина — до 150 знаков.
+
+```
+feat(site): availability calendar with season prices
+fix(api): reject overlapping booking dates
+chore(deploy): docker-compose for vps
+```
+
+## Документ едет тем же коммитом
+
+`docs-guard` требует пару и называет её сам. Обход — строка в теле, причина обязательна:
+
+```
+Docs-skip: правка только в тестах хука, зеркала у него нет
+```
+
+## Номер задачи стоит в её заголовке и в заголовке PR
+
+Форма одна на оба — `[<КЛЮЧ>-<номер>] <текст>`. Номер стоит в самом заголовке, а не только в
+теле: в списке PR тела не видно, а в списке задач номер иначе приходится искать глазами по
+колонке слева. Тот же номер несёт и имя ветки — `<КЛЮЧ>-<номер>-<короткий-slug>`, — поэтому
+задача, ветка и PR читаются как одно.
+
+Задача говорит, что не так; PR тем же номером отчитывается, что сделано:
+
+```
+задача  [<КЛЮЧ>-86] Пустой MAIL_OWNER — письма владельцу не уходят молча
+PR      [<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи
+
+задача  [<КЛЮЧ>-101] Вернуть оверлей загрузки таблицы и включить stylelint гейтом
+PR      [<КЛЮЧ>-101] Stylelint включён гейтом
+
+задача  [<КЛЮЧ>-212] Сайт не собирается: компонентам кита проставлен префикс vm- вместо rt-
+PR      [<КЛЮЧ>-212] Виджет переписки зовёт кит его собственными именами
+```
+
+Инфинитив из задачи в заголовок PR не переносится: «исправить» становится «исправлено»,
+«вернуть» — «возвращено», «добавить» — «добавлено».
+
+Номер в заголовке обязан совпасть с номером ветки: гард поставки сверяет их до отправки
+команды, а сверка очереди — у каждого открытого PR.
+
+Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
+коммита, и там его сверяет `commitlint`. В списке PR он занимает место, ничего не добавляя:
+род правки и область уже видны метками.
+
+## PR прикрепляется к задаче
+
+Тело начинается со строки связи — по ней на борде заполняется поле «Linked pull requests».
+Ревьювер, исполнитель и метки задаются той же командой, и PR без них не открывается:
+
+```bash
+GH_TOKEN="$TOKEN" gh pr create --title '[<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи' \
+    --reviewer <владелец> --assignee <бот> --label bug --label area:api \
+    --body 'Closes #86
+
+…'
+```
+
+Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Исполнитель —
+та же учётная запись, от которой идёт машинная работа. Метки берутся у задачи целиком — и род
+правки, и все её области; читаются они у задачи, а не выбираются по памяти:
+
+```bash
+/opt/homebrew/bin/gh issue view 86 --json labels --jq '.labels | map(.name) | join(",")'
+```
+
+Строка `Closes #<номер>` обязательна: без неё PR не прикрепляется к задаче, и сверка очереди
+это находит. Она же и означает, что задача закрывается целиком — половину задачи одним PR не
+выкатывают: у задачи одна ветка, и работа, которая в неё не влезает, делится на задачи до
+того, как ветка заводится.
+
+У уже открытого PR то же ставится тремя вызовами REST. `gh pr edit` здесь не годится: он
+запрашивает карточки Projects (classic), получает отказ о снятом API и до правки не доходит.
+
+```bash
+GH=/opt/homebrew/bin/gh
+REPO=<владелец>/<репозиторий>
+
+$GH api -X POST "repos/$REPO/issues/205/labels" -f 'labels[]=bug' -f 'labels[]=area:api'
+$GH api -X POST "repos/$REPO/issues/205/assignees" -f 'assignees[]=<бот>'
+$GH api -X POST "repos/$REPO/pulls/205/requested_reviewers" -f 'reviewers[]=<владелец>'
+```
+
+Тем же вызовом правится и само тело: `-f body=` переписывает его целиком, поэтому строка
+`Closes #<номер>` пишется заново вместе с остальным текстом.
+
+```bash
+$GH api -X PATCH "repos/$REPO/pulls/205" -f body="$(cat тело.md)"
+```
+
+Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: отчёт
+утверждает про дерево, а дерево с тех пор изменилось.
+
+## Состояние PR читается, а не додумывается
+
+Вызовы, которыми ставятся ревьювер, метки и исполнитель, отвечают нулевым кодом и тогда, когда
+ничего не сделали: запрос разбора на автора PR GitHub молча выбрасывает. Поэтому после них PR
+перечитывают:
+
+```bash
+# Ключи латиницей: кириллический ключ без кавычек `jq` не разбирает и падает на нём
+$GH api "repos/$REPO/pulls/321" \
+    --jq '{author: .user.login, reviewers: [.requested_reviewers[].login], labels: [.labels[].name]}'
+```
+
+Автор здесь — `<бот>`. Если им оказался владелец, ревьювера у PR не будет вовсе:
+назначить автора ревьювером нельзя, а отказа на такой запрос не приходит. Владельцу называют
+то, что прочитали, а не то, что заказывали.
+
+Учётная запись, из-под которой пришлось пушить, в этот вызов не переносится: пуш и авторство
+PR выбираются отдельно, и `GH_TOKEN` для публикации — всегда токен бота.
+
+Открытый PR означает, что задача ждёт разбора, — колонка переставляется тем же движением:
+
+```bash
+npm run task:move -- 86 in-review
+```
+
+Голым GraphQL по идентификаторам проекта, элемента и варианта поля это не пишется: команда
+знает их сама, а собранный по памяти запрос молча ставит не ту колонку — отказа у борды на
+это нет.
+
+## Что проверяется до публикации PR
+
+Проверок на самом PR нет: выкатка запускается пушем в главную ветку, и до мержа никто не
+гоняет ничего. Линтеры, юниты и сценарии хуков снимает гейт пуша — ниже то, чего он не знает.
+
+1. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
+   домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
+2. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
+   целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
+3. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
+   поведения он не знает — это остаётся за автором.
+4. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`: сверка
+   сценариев с тестами, путей в документах, раскладки либ, повторов и классов без правила.
+   Какие именно есть здесь — `implementation.md` правила.
+5. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет:
+   она длиннее всего, что он успевает сделать между командой и пушем.
+6. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
+   переводится.
+7. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
+   `browser-verification-measure`.
+8. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** — паттерн
+   `seo-verify`.
+9. **Тело PR начинается строкой `Closes #<номер>`**, а метки, ревьювер и исполнитель стоят.
+10. **Заголовок PR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что сделано>`,
+    тем же номером, что стоит у задачи и в имени ветки. Инфинитив из задачи в него не
+    переносится, тип и область коммита — тоже.
+11. **Очередь работ сходится** — `npm run check:board`. Задача на борде, с исполнителем и
+    номером в заголовке; PR один на задачу, и закрывает он её целиком.
+12. **Состояние PR прочитано, а не выведено из кодов возврата** — автор `<бот>`,
+    ревьювер — владелец, метки те же, что у задачи. Владельцу называют прочитанное.
+
+Сразу после публикации задача переставляется в разбор — `npm run task:move -- <номер>
+in-review`, — и `npm run check:board` прогоняется ещё раз: до открытия PR колонку он не судит,
+а после открытия расхождение видит.
+
+Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
+названное проверенным, ревьювер принимает за проверенное.
+
+## Частые промахи
+
+- `gh` в оболочке пользователя подменён — звать `/opt/homebrew/bin/gh` напрямую.
+- `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
+  команда обрывается на первом промахе целиком, а не пропускает его. Следующий
+  `git commit --amend` при этом уносит в коммит всё, что осталось в индексе, — так в коммит
+  уехало удаление файла, принадлежавшее соседней ветке. Состав коммита читается
+  `git show --stat` сразу после него, а не на разборе PR.
+- Состав индекса читается `git diff --cached --stat` **до** коммита, а не только `git show --stat`
+  после него. Команды дерева кладут файлы в индекс сами: `npm run task:new` добавляет папку
+  задачи, и вместе с ней уезжает всё, что лежало рядом, — так в индексе оказался временный
+  каталог диагностики.
+- `gh project` с `--owner` отвечает `unknown owner type`: владелец борды — другая учётная
+  запись, и правка идёт только через GraphQL.
+- Заведённый тикет на борду сама она не забирает: репозиторий с ней не связан, и добавление
+  идёт отдельным вызовом. Два тикета так и остались вне очереди работ — поэтому все четыре
+  шага и делает `npm run task:new`, а не рука.
+- Исполнитель у задачи не проставляется сам ни при заведении через веб, ни при добавлении на
+  борду: из девяноста девяти открытых задач он стоял у двух.
+- Задача, заведённая через веб, мимо команды, на борду не попадает и гардом не отбивается —
+  он смотрит команду, а не тикет. Ловится это только сверкой очереди.
+- Колонка задачи сама не двигается ни от заведения ветки, ни от открытия PR: борда ветки не
+  видит вовсе, а связь с PR заполняет только поле «Linked pull requests». Взятие в работу не
+  ловит и сверка — ей ветка тоже не видна.
+- `gh api graphql --paginate` на запросе элементов борды уходит в повтор первой страницы:
+  курсор берётся из ответа руками, а полнота сверяется с `items(first: 1) { totalCount }`.
+- Второй строкой `Closes` в одном PR задача больше не закрывается: две задачи в одной ветке
+  откатываются только вместе. Либо это одна задача — и вторая поглощается, — либо две ветки.
+- Половина задачи, уехавшая своим PR, тоже промах: тело такого PR начинается со слов «Часть
+  #<номер>» вместо `Closes`, задача остаётся открытой, и после отката видно её целой. Работа,
+  которая в одну ветку не влезает, делится на задачи до того, как ветка заводится.
+- PR открыт без ревьювера: он не попадает во входящие владельца вовсе, и очередь стоит,
+  выглядя работающей. Так шестнадцать PR ждали разбора, которого никто не запрашивал.
+- Метки поставлены по названию PR, а не прочитаны у задачи: область теряется, и по борде не
+  видно, что правка задела ещё и сайт.
+- Задача закрыта не полностью, а метки перенесены целиком: тикет остаётся открытым, и это
+  говорится в теле PR, а не подразумевается строкой `Closes`.
+- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.

package/assets/patterns/git-workflow-commit.gitlab.md

@@ -0,0 +1,283 @@
+---
+name: git-workflow-commit
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow для дерева на GitLab. Брать на заведение задачи, ветки, коммит, пуш и создание MR — заведение задачи со всеми шагами, перевод по спискам доски, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки MR, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+---
+
+# Ветка, коммит и MR
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Заводится задача, с которой начинается правка.
+- Заводится ветка под задачу.
+- Готовится коммит или пуш.
+- Открывается MR.
+- Работа перешла на следующий шаг, и задача переставляется в другой список доски.
+
+## Сначала задача на доске, потом ветка
+
+Заведение состоит из четырёх шагов: issue, номер в его заголовке, исполнитель, метка первого
+списка доски. Доска показывает те issue, чью метку знает, — поэтому четвёртый шаг сам не
+случается, и задача без него заведена, но в очереди работ её нет.
+
+Все четыре делает одна команда дерева, а не рука: делить их значит забывать последний.
+
+```bash
+npm run task:new -- --title 'Письма владельцу не уходят молча' \
+    --label bug --label area:api --slug mail-owner-silence < описание.md
+```
+
+Тело читается со стандартного ввода, `--slug` необязателен и идёт только в подсказку с именем
+ветки. Автор и исполнитель — учётная запись машинной работы; токен команда читает сама, из
+файла вне репозитория.
+
+Скрипт под этой командой заводит проект — пакет её не везёт. Что он делает вызовами `glab`:
+
+```bash
+glab issue create --title '[<КЛЮЧ>-<номер>] …' --label bug --label 'status::backlog' \
+    --assignee <бот> --description-file -
+glab issue update <номер> --title '[<КЛЮЧ>-<номер>] …'   # номер известен только после создания
+```
+
+Метка списка ставится при заведении, а не после: issue без неё лежит вне доски, и увидеть её
+можно только поиском по проекту.
+
+Чем сверить, что очередь работ в порядке:
+
+```bash
+npm run check:board
+```
+
+Она смотрит только открытое: метку списка, номер и исполнителя у каждой открытой задачи, а у
+каждого открытого MR — номер в заголовке, строку `Closes`, открытую задачу за ним и то, что
+второго MR с тем же номером нет. Имя ветки не судит: у открытого MR его не переименовать.
+
+## Две задачи, которые чинятся одной правкой
+
+Если по ходу выяснилось, что правка закрывает и соседнюю задачу, — это одна задача, а не две.
+Слить их можно, пока правка не въехала в главную ветку:
+
+```bash
+# то, чего в поглотившей задаче не было, дописывается в её описание
+glab issue update <поглотившая> --description "$(cat тело.md)"
+# поглощённая закрывается как дубликат, со ссылкой на поглотившую
+glab issue note <поглощённая> --message 'Дубликат #<поглотившая>: чинится той же правкой.'
+glab issue close <поглощённая>
+```
+
+Закрытая как дубликат уходит из очереди работ, а её номер остаётся в истории — этим GitLab
+отличается от хостингов, где задачу можно стереть. Ссылка на поглотившую обязательна: без неё
+закрытая задача читается как сделанная, а сделана она не была.
+
+После слияния ветки поглощения нет: она въехала, и откатывается целиком.
+
+## Ветка заводится отдельным вызовом
+
+Гард главной ветки разбирает текст команды и смотрит ветку на момент запуска, поэтому
+составная команда отклоняется целиком — ветки в ней ещё нет:
+
+```bash
+✗ git checkout -b <КЛЮЧ>-85-guest-token && git commit -m 'feat(admin): …'
+✓ git checkout -b <КЛЮЧ>-85-guest-token
+✓ git commit -F -
+```
+
+Имя — `<КЛЮЧ>-<номер задачи>-<короткий-slug>`, slug строчными латинскими через дефис. Гард
+поставки разбирает его на месте и отбивает промах в форме до первого коммита, а по номеру
+спрашивает доску: задача должна существовать, быть открытой, стоять в очереди и иметь
+исполнителя.
+
+Имя без номера (`feat/…`, `fix/…`) законно, пока ветка живёт локально — под пробу и разбор.
+MR с неё не откроется: правка, доезжающая до главной ветки, начинается с задачи.
+
+## Список задачи двигается вместе с работой
+
+Ветка заведена — задача уже не в первом списке, а в работе. MR открыт — она ждёт разбора.
+Оба перевода делает одна команда, вторым вызовом сразу за тем, который его вызвал:
+
+```bash
+npm run task:move -- 86 in-progress   # сразу после git checkout -b <КЛЮЧ>-86-…
+npm run task:move -- 86 in-review     # сразу после glab mr create
+```
+
+Списки доски — это метки, поэтому перевод обязан снять прежнюю:
+
+```bash
+glab issue update 86 --label 'status::in-progress' --unlabel 'status::backlog'
+```
+
+Перевод, не снявший прежнюю метку, оставляет задачу в двух списках сразу, и очередь читается
+неверно — в обоих местах она выглядит настоящей.
+
+Перевод не откладывается на потом: очередь работ читают между шагами, а не после них.
+
+## Коммит подписывается учётной записью машинной работы
+
+Токен читается в переменную и не печатается; автор и коммиттер задаются переменными той же
+команды. `git config` не годится — конфиг общий с основным деревом и переписал бы подпись
+владельцу:
+
+```bash
+TOKEN=$(tr -d '\n' < ~/.config/<дерево>-bot-token)
+
+GIT_AUTHOR_NAME="<бот>" GIT_AUTHOR_EMAIL="<почта бота>" \
+GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<почта бота>" \
+    git commit -F -
+```
+
+Заголовок — `type(scope): description`. Типы: `feat`, `fix`, `refactor`, `docs`, `style`,
+`test`, `chore`, `perf`. Области — свои у дерева, они перечислены в `implementation.md`. Точка
+в конце заголовка не принимается.
+
+```
+feat(site): availability calendar with season prices
+fix(api): reject overlapping booking dates
+chore(deploy): docker-compose for vps
+```
+
+## Документ едет тем же коммитом
+
+`docs-guard` требует пару и называет её сам. Обход — строка в теле, причина обязательна:
+
+```
+Docs-skip: правка только в тестах хука, зеркала у него нет
+```
+
+## Номер задачи стоит в её заголовке и в заголовке MR
+
+Форма одна на оба — `[<КЛЮЧ>-<номер>] <текст>`. Номер стоит в самом заголовке, а не только в
+теле: в списке MR тела не видно, а в списке задач номер иначе приходится искать глазами. Тот же
+номер несёт и имя ветки, поэтому задача, ветка и MR читаются как одно.
+
+Задача говорит, что не так; MR тем же номером отчитывается, что сделано:
+
+```
+задача  [<КЛЮЧ>-86] Пустой адрес владельца — письма не уходят молча
+MR      [<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи
+```
+
+Инфинитив из задачи в заголовок MR не переносится: «исправить» становится «исправлено»,
+«вернуть» — «возвращено», «добавить» — «добавлено».
+
+Тип и область — `fix(site):`, `docs(common):` — в заголовок MR не идут: это формат заголовка
+коммита, и там его сверяет `commitlint`. В списке MR он занимает место, ничего не добавляя:
+род правки и область уже видны метками.
+
+## MR прикрепляется к задаче
+
+Описание начинается со строки связи. Ревьювер, исполнитель и метки задаются той же командой, и
+MR без них не открывается:
+
+```bash
+GITLAB_TOKEN="$TOKEN" glab mr create \
+    --title '[<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи' \
+    --assignee <бот> --reviewer <владелец> --label bug --label area:api \
+    --target-branch main --remove-source-branch \
+    --description 'Closes #86
+
+…'
+```
+
+Ревьювер — всегда владелец: без запроса разбора MR не показывается ему в очереди. Исполнитель —
+та же учётная запись, от которой идёт машинная работа. Метки читаются у задачи, а не выбираются
+по памяти:
+
+```bash
+glab issue view 86 --output json | jq -r '[.labels[]] | join(",")'
+```
+
+Строка `Closes #<номер>` обязательна: без неё MR не прикрепляется к задаче, и сверка очереди
+это находит. Она же означает, что задача закрывается целиком — половину задачи одним MR не
+выкатывают: у задачи одна ветка, и работа, которая в неё не влезает, делится на задачи до того,
+как ветка заводится.
+
+У уже открытого MR то же ставится правкой:
+
+```bash
+glab mr update 205 --label bug --label area:api --assignee <бот> --reviewer <владелец>
+glab mr update 205 --description "$(cat тело.md)"
+```
+
+Правка описания переписывает его целиком, поэтому строка `Closes #<номер>` пишется заново
+вместе с остальным текстом. Тело перечитывается всякий раз, когда в ветку что-то влилось после
+публикации: отчёт утверждает про дерево, а дерево с тех пор изменилось.
+
+## Состояние MR читается, а не додумывается
+
+Команды правки отвечают нулевым кодом и тогда, когда ничего не сделали: токен без права на
+проект молча не ставит ни метку, ни ревьювера. Поэтому после них MR перечитывают:
+
+```bash
+glab mr view 205 --output json \
+    | jq '{author: .author.username, reviewers: [.reviewers[].username], labels: .labels}'
+```
+
+Владельцу называют то, что прочитали, а не то, что заказывали.
+
+Учётная запись, из-под которой пришлось пушить, в этот вызов не переносится: пуш и авторство
+MR выбираются отдельно, и токен для публикации — всегда токен машинной работы.
+
+Открытый MR означает, что задача ждёт разбора, — список переставляется тем же движением:
+
+```bash
+npm run task:move -- 86 in-review
+```
+
+## Что проверяется до публикации MR
+
+Проверок на самом MR нет ровно до тех пор, пока конвейер не запущен, а запускается он пушем.
+Линтеры, юниты и сценарии хуков снимает гейт пуша — ниже то, чего он не знает.
+
+1. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
+   домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
+2. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
+   целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
+3. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
+   поведения он не знает — это остаётся за автором.
+4. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`. Какие именно
+   есть здесь — `implementation.md` правила.
+5. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет.
+6. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
+   переводится.
+7. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
+   `browser-verification-measure`.
+8. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** —
+   паттерн `seo-verify`.
+9. **Описание MR начинается строкой `Closes #<номер>`**, а метки, ревьювер и исполнитель стоят.
+10. **Заголовок MR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что
+сделано>`, тем же номером, что стоит у задачи и в имени ветки.
+11. **Очередь работ сходится** — `npm run check:board`.
+12. **Состояние MR прочитано, а не выведено из кодов возврата.**
+
+Сразу после публикации задача переставляется в разбор, и сверка очереди прогоняется ещё раз: до
+открытия MR список она не судит, а после открытия расхождение видит.
+
+Сделанное рассуждением и сделанное замером в теле MR разводятся прямо: непроверенное,
+названное проверенным, ревьювер принимает за проверенное.
+
+## Частые промахи
+
+- Метка списка не поставлена при заведении: задача есть, а на доске её нет. Доска показывает
+  только то, чью метку знает.
+- Перевод по списку не снял прежнюю метку: задача стоит в двух списках сразу.
+- `glab` не видит проект: у токена область `read_api` вместо `api`. Команды правки при этом
+  отвечают успехом и не делают ничего.
+- `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
+  команда обрывается на первом промахе целиком. Следующий `git commit --amend` при этом уносит
+  в коммит всё, что осталось в индексе. Состав коммита читается `git show --stat` сразу после
+  него, а не на разборе MR.
+- MR открыт без ревьювера: он не попадает во входящие владельца, и очередь стоит, выглядя
+  работающей.
+- Метки поставлены по названию MR, а не прочитаны у задачи: область теряется, и по доске не
+  видно, что правка задела ещё и соседний домен.
+- Вторая строка `Closes` в одном MR: две задачи в одной ветке откатываются только вместе. Либо
+  это одна задача — и вторая поглощается, — либо две ветки.
+- Половина задачи, уехавшая своим MR: описание такого MR начинается со слов «Часть #<номер>»
+  вместо `Closes`, задача остаётся открытой, и после отката видно её целой.
+- `--remove-source-branch` забыт: ветки задач копятся в репозитории, и по списку веток больше
+  не видно, какая работа идёт сейчас.
+- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.