@rt-tools/agent-kit 0.2.0 → 0.4.0

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

@@ -0,0 +1,259 @@
+---
+name: git-workflow-commit
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow для дерева в Azure DevOps. Брать на заведение рабочего элемента, ветки, коммит, пуш и создание PR — заведение элемента со всеми шагами, перевод по состояниям, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, привязка PR к элементу, ревьювер, исполнитель и метки, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+---
+
+# Ветка, коммит и PR
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Заводится рабочий элемент, с которого начинается правка.
+- Заводится ветка под него.
+- Готовится коммит или пуш.
+- Открывается PR.
+- Работа перешла на следующий шаг, и элемент переводится в другое состояние.
+
+## Сначала рабочий элемент, потом ветка
+
+Заведение состоит из четырёх шагов: элемент, номер в его заголовке, исполнитель, состояние
+`New`. Область и итерация ставятся тут же: элемент без них лежит в корне проекта и на доску
+команды не попадает — заведён, а в очереди работ его нет.
+
+Все четыре делает одна команда дерева, а не рука: делить их значит забывать последний.
+
+```bash
+npm run task:new -- --title 'Письма владельцу не уходят молча' \
+    --type Bug --area '<проект>\<команда>' --slug mail-owner-silence < описание.md
+```
+
+Скрипт под этой командой заводит проект — пакет её не везёт. Что он делает вызовами `az`:
+
+```bash
+az boards work-item create --type Bug --title '[<номер>] …' \
+    --org https://dev.azure.com/<организация> --project <проект> \
+    --assigned-to <бот> --area '<проект>\<команда>' --iteration '<проект>\<итерация>'
+az boards work-item update --id <номер> --title '[<номер>] …'   # номер известен после создания
+```
+
+Номер в заголовок руками не пишется — он известен только после создания, и команда дописывает
+его сама.
+
+Чем сверить, что очередь работ в порядке:
+
+```bash
+npm run check:board
+```
+
+Она смотрит только открытое: состояние, область и исполнителя у каждого открытого элемента, а
+у каждого открытого PR — номер в заголовке, привязанный элемент и то, что второго PR с тем же
+номером нет. Имя ветки не судит: у открытого PR его не переименовать.
+
+## Две задачи, которые чинятся одной правкой
+
+Если по ходу выяснилось, что правка закрывает и соседний элемент, — это одна задача, а не две.
+Слить их можно, пока правка не въехала в главную ветку:
+
+```bash
+# то, чего в поглотившем элементе не было, дописывается в его описание
+az boards work-item update --id <поглотивший> --description "$(cat тело.md)"
+# поглощённый связывается с ним как дубликат и закрывается
+az boards work-item relation add --id <поглощённый> --relation-type duplicate-of \
+    --target-id <поглотивший>
+az boards work-item update --id <поглощённый> --state 'Removed'
+```
+
+Связь ставится до закрытия: закрытый без неё элемент читается как сделанный, а сделан он не
+был. Состояние снятого зависит от процесса проекта — `Removed` есть в Agile и Scrum, в Basic
+его нет; какое здесь, сказано в `implementation.md`.
+
+После слияния ветки поглощения нет: она въехала, и откатывается целиком.
+
+## Ветка заводится отдельным вызовом
+
+Гард главной ветки разбирает текст команды и смотрит ветку на момент запуска, поэтому
+составная команда отклоняется целиком — ветки в ней ещё нет:
+
+```bash
+✗ git checkout -b 85-guest-token && git commit -m 'feat(admin): …'
+✓ git checkout -b 85-guest-token
+✓ git commit -F -
+```
+
+Имя несёт номер элемента, slug строчными латинскими через дефис; точная форма — в
+`implementation.md`. Гард поставки разбирает её на месте и отбивает промах до первого коммита,
+а по номеру спрашивает доску: элемент должен существовать, быть открытым и иметь исполнителя.
+
+Имя без номера (`feat/…`, `fix/…`) законно, пока ветка живёт локально — под пробу и разбор.
+PR с неё не откроется: правка, доезжающая до главной ветки, начинается с задачи.
+
+## Состояние элемента двигается вместе с работой
+
+Ветка заведена — элемент уже не `New`, а `Active`. PR открыт — он ждёт разбора. Оба перевода
+делает одна команда, вторым вызовом сразу за тем, который его вызвал:
+
+```bash
+npm run task:move -- 86 in-progress   # сразу после git checkout -b 86-…
+npm run task:move -- 86 in-review     # сразу после az repos pr create
+```
+
+Под ней — правка поля состояния:
+
+```bash
+az boards work-item update --id 86 --state 'Active'
+```
+
+Имена состояний берутся у процесса проекта, а не назначаются правилом: Agile, Scrum и Basic
+называют одни и те же три шага по-разному, и перевод в состояние, которого в процессе нет,
+отвечает отказом на каждой задаче подряд.
+
+Перевод не откладывается на потом: очередь работ читают между шагами, а не после них.
+
+## Коммит подписывается учётной записью машинной работы
+
+Токен читается в переменную и не печатается; автор и коммиттер задаются переменными той же
+команды. `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`. Точка
+в конце заголовка не принимается.
+
+Строка `AB#<номер>` в теле коммита привязывает его к рабочему элементу. Она не заменяет
+привязки самого PR: коммит связывается с элементом, а очередь работ читает связь PR.
+
+## Документ едет тем же коммитом
+
+`docs-guard` требует пару и называет её сам. Обход — строка в теле, причина обязательна:
+
+```
+Docs-skip: правка только в тестах хука, зеркала у него нет
+```
+
+## Номер элемента стоит в его заголовке и в заголовке PR
+
+Форма одна на оба — `[<номер>] <текст>`. Номер стоит в самом заголовке, а не только в теле: в
+списке PR тела не видно. Тот же номер несёт и имя ветки, поэтому элемент, ветка и PR читаются
+как одно.
+
+Элемент говорит, что не так; PR тем же номером отчитывается, что сделано:
+
+```
+элемент  [86] Пустой адрес владельца — письма не уходят молча
+PR       [86] Письмо владельцу с незаполненным адресом попадает в логи
+```
+
+Инфинитив в заголовок PR не переносится: «исправить» становится «исправлено», «вернуть» —
+«возвращено», «добавить» — «добавлено».
+
+Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
+коммита, и там его сверяет `commitlint`.
+
+## PR привязывается к элементу при создании
+
+Привязка задаётся флагом, а не правкой после: у токена может не быть права править чужой
+элемент, и вторая команда обойдётся молча, оставив PR ни с чем не связанным.
+
+```bash
+AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create \
+    --title '[86] Письмо владельцу с незаполненным адресом попадает в логи' \
+    --source-branch 86-mail-owner-silence --target-branch main \
+    --work-items 86 --reviewers <владелец> --delete-source-branch true \
+    --description 'Закрывает рабочий элемент 86.'
+```
+
+Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Один PR
+закрывает элемент целиком — половину задачи одним PR не выкатывают: у задачи одна ветка, и
+работа, которая в неё не влезает, делится на задачи до того, как ветка заводится.
+
+У уже открытого PR то же ставится правкой:
+
+```bash
+az repos pr work-item add --id 205 --work-items 86
+az repos pr reviewer add --id 205 --reviewers <владелец>
+az repos pr update --id 205 --description "$(cat тело.md)"
+```
+
+Правка описания переписывает его целиком. Тело перечитывается всякий раз, когда в ветку что-то
+влилось после публикации: отчёт утверждает про дерево, а дерево с тех пор изменилось.
+
+## Состояние PR читается, а не додумывается
+
+Команды правки отвечают нулевым кодом и тогда, когда ничего не сделали. Поэтому после них PR
+перечитывают:
+
+```bash
+az repos pr show --id 205 \
+    --query '{author: createdBy.uniqueName, reviewers: reviewers[].uniqueName, work: workItemRefs[].id}'
+```
+
+Владельцу называют то, что прочитали, а не то, что заказывали.
+
+Открытый PR означает, что элемент ждёт разбора, — состояние переставляется тем же движением:
+
+```bash
+npm run task:move -- 86 in-review
+```
+
+## Что проверяется до публикации 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 привязан к рабочему элементу**, ревьювер и исполнитель стоят.
+10. **Заголовок PR несёт номер элемента и называет работу сделанной:** `[<номер>] <Что
+сделано>`, тем же номером, что стоит у элемента и в имени ветки.
+11. **Очередь работ сходится** — `npm run check:board`.
+12. **Состояние PR прочитано, а не выведено из кодов возврата.**
+
+Сразу после публикации элемент переводится в разбор, и сверка очереди прогоняется ещё раз: до
+открытия PR состояние она не судит, а после открытия расхождение видит.
+
+Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
+названное проверенным, ревьювер принимает за проверенное.
+
+## Частые промахи
+
+- Область и итерация не заданы: элемент заведён, но на доску команды не попал.
+- Состояние взято не из процесса проекта: перевод отвечает отказом на каждой задаче, и это
+  читается как сломанная команда, а не как неверное имя состояния.
+- PR открыт без `--work-items`: связи нет, и по очереди работ не видно, за чем эта правка.
+- `AB#<номер>` в коммите принят за привязку PR: он связывает коммит, а очередь читает связь PR.
+- `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
+  команда обрывается на первом промахе целиком. Следующий `git commit --amend` при этом уносит
+  в коммит всё, что осталось в индексе. Состав коммита читается `git show --stat` сразу после
+  него, а не на разборе PR.
+- PR открыт без ревьювера: он не попадает во входящие владельца, и очередь стоит, выглядя
+  работающей.
+- `--delete-source-branch` забыт: ветки задач копятся в репозитории, и по списку веток больше
+  не видно, какая работа идёт сейчас.
+- Автозавершение включено до того, как прогнаны проверки до пуша: конвейер зелёный на том, что
+  он умеет, и слияние происходит без всего остального.
+- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.

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

@@ -0,0 +1,333 @@
+---
+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.
+- `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`.
+- Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.