@rt-tools/agent-kit 0.2.0 → 0.4.0

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

package/assets/patterns/git-workflow-merge.md

@@ -0,0 +1,99 @@
+---
+name: git-workflow-merge
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать, когда главная ветка вливается в ветку задачи и разрешается конфликт — порядок мержа, разбор конфликта по роду файла, сверка дописанного веткой с очередью работ, проверки после разрешения, перечитывание тела уже открытого PR. Не брать для заведения ветки, коммита и PR — это паттерн git-workflow-commit.
+---
+
+# Мерж главной ветки в ветку задачи
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- PR отмечен конфликтующим, и его надо вернуть к сливаемому состоянию.
+- Главная ветка ушла вперёд, и ветку задачи надо подтянуть до проверок.
+- Коммит переносится черри-пиком.
+
+## Порядок
+
+```bash
+git fetch origin
+git merge origin/main --no-edit
+git diff --name-only --diff-filter=U     # что встало конфликтом
+```
+
+Список конфликтов читается целиком до первого разрешения: род файла решает приём, и разные
+файлы одного мержа разрешаются по-разному.
+
+| Что встало конфликтом            | Как разрешается                                                                    |
+| -------------------------------- | ---------------------------------------------------------------------------------- |
+| код                              | ловушка правила `git-workflow` про сторону-удаление; после — `npm run check:dupes` |
+| спек в `docs/specs/`             | сохранением обеих сторон — правило `spec-driven`; после — `npm run check:specs`    |
+| список работ (`docs/BACKLOG.md`) | признаком отбора — паттерн `doc-style-sweep`                                       |
+
+## Что дописала ветка, видно только от точки расхождения
+
+Конфликтный маркер показывает место, а не правку: сторона ветки в нём — её допись вместе со
+всем, что лежало в файле до неё.
+
+```bash
+git diff "$(git merge-base origin/main HEAD)" HEAD -- docs/BACKLOG.md
+```
+
+## Дописанное веткой сверяется с очередью работ, а не переносится по умолчанию
+
+Раздел, который ветка дописала в список работ, к моменту мержа обычно уже стоит задачей:
+ветка живёт неделями, а замеченный по ходу дефект заводится задачей сразу. Перенести его
+второй раз — завести вторую запись об одной работе.
+
+```bash
+/opt/homebrew/bin/gh issue list --state all --limit 400 --search '<слова из раздела>' \
+    --json number,title,state
+```
+
+Задача несёт то же содержание — сторона ветки не переносится:
+
+```bash
+git checkout --theirs docs/BACKLOG.md && git add docs/BACKLOG.md
+```
+
+В мерже `--theirs` — влитая главная ветка, а `--ours` — ветка задачи; при перебазировании
+стороны меняются местами. Взятая не та сторона стирает работу молча.
+
+## Проверки после разрешения
+
+Конфликт в текстах кода не задевает, и зелёная сборка про него ничего не говорит:
+
+```bash
+grep -rn '^<<<<<<< \|^>>>>>>> ' --exclude-dir=node_modules --exclude-dir=.git .
+npm run check:docs && npm run check:specs && npm run check:dupes && npm run check:board
+bash .claude/hooks/tests/run.sh       # если конфликт задел хуки
+```
+
+Коммит мержа подписывается ботом тем же способом, что и любой другой, — паттерн
+`git-workflow-commit`. После пуша состояние читается у самого PR, а не по своему дереву:
+
+```bash
+/opt/homebrew/bin/gh pr view <номер> --json mergeable,mergeStateStatus
+```
+
+## Тело открытого PR перечитывается после мержа
+
+Отчёт описывал дерево на день, когда его написали. Мерж главной ветки меняет то, о чём он
+утверждает: тело говорило, что оба дефекта заведены в `docs/BACKLOG.md`, а главная ветка этот
+список к тому времени разобрала. Правится тело вызовом REST — `gh pr edit` в этом репозитории
+отвечает отказом про Projects (classic) и до правки не доходит:
+
+```bash
+/opt/homebrew/bin/gh api -X PATCH repos/<владелец>/<репозиторий>/pulls/<номер> -f body="$(cat тело.md)"
+```
+
+## Частые промахи
+
+- «Сохранить обе стороны» применено ко всем файлам одинаково: в спеке это верно, в коде и в
+  списке работ — нет.
+- Сторона ветки перенесена без сверки с очередью работ: одна работа стала двумя записями.
+- После разрешения прогнана сборка, а проверки текстов — нет: конфликта в них сборке не видно.
+- Тело PR оставлено прежним: ревьювер читает утверждение о дереве, которого больше нет.

package/assets/patterns/git-workflow-migration.md

@@ -0,0 +1,88 @@
+---
+name: git-workflow-migration
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при правке prisma/schema.prisma и prisma/migrations/** — готовые команды одноразового контейнера, написание файла миграции через migrate diff, накат локальной базы. Не брать для коммита и PR — это паттерн git-workflow-commit.
+---
+
+# Миграция и прогон цепочки
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Правится `prisma/schema.prisma`.
+- Заводится или переименовывается каталог в `prisma/migrations/`.
+- Ветка с новой миграцией готовится к мержу.
+
+## Цепочка гоняется одной командой
+
+Локальные `lint`, `test`, `check:all` и сборки порядок миграций не трогают вовсе, а шаг
+`Migrations match schema` в `.github/workflows/deploy.yml` идёт уже после мержа. Проверка
+стоит гейтом пуша и зовётся руками:
+
+```bash
+npm run check:schema
+```
+
+Она накатывает цепочку на теневую базу — ту же, что рабочая, с суффиксом `_gate_shadow`, —
+сравнивает её со схемой и сносит. Своя база при этом не трогается: сверка с ней судила бы о
+состоянии машины, а не репозитория. Погашенный докер и боевой адрес проверка пропускает
+молча.
+
+Когда базы под рукой нет вовсе, та же цепочка гоняется на одноразовом контейнере:
+
+```bash
+docker run -d --rm --name <префикс>-migcheck -e POSTGRES_PASSWORD=migcheck -p 55432:5432 postgres:16-alpine
+docker exec <префикс>-migcheck pg_isready -U postgres          # накат до готовности падает на соединении
+DATABASE_URL=postgresql://postgres:migcheck@localhost:55432/postgres npx prisma migrate deploy
+DATABASE_URL=postgresql://postgres:migcheck@localhost:55432/postgres npx prisma migrate diff \
+    --from-config-datasource --to-schema prisma/schema.prisma --exit-code
+docker stop <префикс>-migcheck
+```
+
+Адрес ставится префиксом самой команды — `export` между вызовами не живёт.
+
+## Файл миграции пишется тем же контейнером
+
+`prisma migrate dev` не запускается ни командой, ни через `npm run prisma:migrate`: любое
+расхождение состояния он лечит предложением сбросить базу, а в локальной базе лежат объекты и
+брони владельца. Файл берётся разницей между накатанной цепочкой и схемой:
+
+```bash
+DATABASE_URL=postgresql://postgres:migcheck@localhost:55432/postgres npx prisma migrate diff \
+    --from-config-datasource --to-schema prisma/schema.prisma --script \
+    > prisma/migrations/<метка>_<имя>/migration.sql
+```
+
+Каталог заводится **после** наката цепочки: пустой каталог, попавший в `migrate deploy`,
+помечается применённым, и его содержимое на этот контейнер уже не встанет.
+
+## Локальная база догоняет ветку
+
+```bash
+npx prisma migrate deploy
+```
+
+Переименованная миграция остаётся в ней под прежним именем, и накат падает на
+`relation … already exists`. Состояние правится, повторный накат его не чинит:
+
+```bash
+npx prisma migrate resolve --applied <новое имя>
+```
+
+## Частые промахи
+
+- Метку времени ставит момент создания, а порядок применения лексикографический: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит. На существующей базе это
+  незаметно — падает только накат с нуля.
+- Флаги `prisma migrate diff` не те, что в примерах из сети: `--from-url`, `--to-url`,
+  `--shadow-database-url` и `--to-schema-datamodel` сняты, а `prisma db execute` адреса
+  базы не принимает вовсе и берёт его из `prisma.config.ts`. На неизвестный флаг обе команды
+  печатают справку, и промах виден только в ней. Какие флаги есть сейчас, смотрят в
+  `prisma migrate diff --help`, а не в этом тексте.
+- Запись в боевую базу (порт 15432, прод-хост) запрещена совсем: схема меняется миграцией
+  через деплой, данные — через админку.
+- Строки адресуются по первичному ключу, а не по маске: удаление по маске почты однажды унесло
+  вместе с тестовыми записями демонстрационные брони владельца.

package/assets/patterns/git-workflow-restart.md

@@ -0,0 +1,49 @@
+---
+name: git-workflow-restart
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при ручном перезапуске прода — после правки .env.prod, при разборе выкатки, при подъёме контейнера на сервере. Готовые команды с IMAGE_TAG по sha, способ узнать выкаченный sha и чем сверять результат. Не брать для коммита и миграций — это паттерны git-workflow-commit и git-workflow-migration.
+---
+
+# Ручной перезапуск прода
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Правился `.env.prod` и контейнер надо поднять заново.
+- Разбирается, что именно сейчас выкачено.
+- Контейнер поднимается на сервере руками, мимо выкатки по мержу.
+
+## Команда обязана нести sha
+
+`.github/workflows/deploy.yml` выкатывает образы по sha коммита. Без переменной `docker
+compose` подставляет умолчание `latest`, а `latest` в реестре отстаёт от главной ветки — прод
+молча откатывается на старый образ и при этом отвечает:
+
+```bash
+IMAGE_TAG='<sha>' docker compose -f docker-compose.prod.yml --env-file .env.prod pull migrate api ssr web
+IMAGE_TAG='<sha>' docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --no-build --remove-orphans
+```
+
+## Sha берётся до перезапуска
+
+У выкаченного контейнера или у последнего мержа в главную ветку:
+
+```bash
+docker inspect <контейнер> --format '{{.Config.Image}}'
+```
+
+## Сверка идёт по логу, а не по коду ответа
+
+Подмена образа видна только по пропавшим строкам нового кода: сводка `startup` с
+`integrations` из логов исчезает, хотя `API is running` остаётся на месте. После перезапуска —
+тот же `inspect` и наличие ожидаемых строк в логе.
+
+## Частые промахи
+
+- Вывод «прод жив, значит выкатилось» — код ответа подмену образа не показывает.
+- Переменные окружения, секреты и записи имён ставятся **до** мержа: мерж выкатывает сразу,
+  и ветка, зависящая от новой переменной, встаёт на проде до того, как переменную заведут.
+- Заход на сервер по ssh в автоматическом режиме режется правилом — нужен обычный режим.

package/assets/patterns/lib-layers-move.md

@@ -0,0 +1,95 @@
+---
+name: lib-layers-move
+kind: pattern
+rule: lib-layers
+description: Паттерн правила lib-layers. Брать при переносе кода или символа между либами — с чего начинать, в каком порядке двигать домены, что делать с границами, импортами и README обеих либ, и чем проверять. Заведение и удаление самой либы — паттерн lib-layers-new.
+---
+
+# Перенести код между либами
+
+Паттерн правила `lib-layers`. Что при этом должно быть верно — закон
+`docs/constitution/lib-imports.md`.
+
+## Когда брать
+
+- Символ переезжает из одной либы в другую.
+- Домен переносится в новую раскладку.
+- Общий код собирается из копий в одно место.
+
+## Начинать с `docs/plans/`
+
+```bash
+grep -rn "<имя либы>" docs/
+```
+
+Решение о том, куда переезжает код, часто уже принято и записано, а принятое заново с ним
+расходится. Перенос утилит списка из-за этого делался дважды: первая редакция положила их в
+`libs/common/util`, что запрещено первым же пунктом того самого плана, и её пришлось
+откатывать целиком.
+
+## Порядок задаёт граф зависимостей, а не список в плане
+
+Домен переносится после всех, от кого он зависит. Списки доменов в планах отсортированы по
+важности, и следование им в лоб заставляет временно расширять границы.
+
+```bash
+grep -rn "@<область>/<семья>/<домен>" libs/ apps/ | sed 's/:.*//' | sort -u
+```
+
+Рёбра выписываются грепом по алиасам домена и сортируются топологически. Каждая временная
+строка в границах — это ослабленная механическая проверка, ради которой нарезка и затевалась.
+
+## Куда именно кладётся общее
+
+Своя либа заводится тогда, когда ни одна существующая код не видит.
+
+| Кому нужно                             | Куда                                                        |
+| -------------------------------------- | ----------------------------------------------------------- |
+| бэкенду или обоим фронтам, без Angular | `libs/common/util`                                          |
+| только фронтам, тянет Angular          | `common/platform` — сервис и токен, `common/ui` — компонент |
+| предмету, у которого уже есть либа     | в неё: `site-routing`, `i18n`, `photo`, `captcha`           |
+| всем доменам одной семьи               | основание семейства `<семья>/core`                          |
+| всему бэкенду                          | тот слой `util`, что уже перечислен у каждого домена        |
+
+Новых строк в границах при таком переезде не появляется — кроме права видеть контракт, если
+код его читает.
+
+## После переезда
+
+1. **README обеих либ.** У той, откуда файл ушёл, и у той, куда пришёл: README перечисляет, что
+   в либе лежит и кто её зовёт. Ни одна проверка эти тексты не читает.
+2. **Порядок импортов.** Переезд алиаса его ломает, и приходит это ошибкой `prettier/prettier`
+   из линта, а не из сборки:
+
+    ```bash
+    npx nx lint <project> --fix
+    ```
+
+    Флага `--fix` нет у `test` и `build`, поэтому в `run-many -t lint test` его передавать
+    нельзя — падает весь вызов.
+
+3. **Линт по всем затронутым проектам, а не по одному приложению.** Скрипт ошибается молча и не
+   так, как человек: строка импорта не переписывается, а исчезает целиком. При переносе утилит
+   списка так пропали импорты в шести файлах из восьми, и нашёл их прогон по списку проектов —
+   сборка одного приложения до этих файлов не дошла.
+
+    ```bash
+    npx nx run-many -t lint --projects=<список по изменённым файлам>
+    ```
+
+## Проверить
+
+```bash
+npm run check:layers
+npm run check:dupes
+```
+
+Второе обязательно: перенос и есть тот момент, когда копия остаётся на старом месте.
+
+## Частые промахи
+
+- Новый адрес выбран без чтения `docs/plans/` — расходится с уже принятым решением.
+- Порядок переноса взят из списка в плане — приходится временно расширять границы.
+- README поправлен только у одной либы.
+- Линт прогнан по приложению, а не по списку затронутых проектов — пропавшие импорты не видно.
+- Копия осталась на старом месте, а `check:dupes` не гонялся.