@rt-tools/agent-kit 0.2.0 → 0.3.0

package/assets/patterns/doc-style-sweep.md

@@ -0,0 +1,100 @@
+---
+name: doc-style-sweep
+kind: pattern
+rule: doc-style
+description: Паттерн правила doc-style. Брать, когда документ накопил список работ и его надо разобрать на действующее и закрытое — признак отбора, обход по утверждениям, сверка с очередью работ, измерение потерь, куда девать доводы за отсрочку и судьба самого файла. Не брать для написания нового текста — это паттерн doc-style-write.
+---
+
+# Разбор документа, накопившего список работ
+
+Паттерн правила `doc-style`. Что при этом должно быть верно — закон
+`{{lawsDir}}/project-documentation.md`, статья о том, что предстоящая работа перечислена в одном
+месте.
+
+## Когда брать
+
+- Документ перечисляет, что осталось сделать, а очередь работ перечисляет то же самое.
+- Файл вырос настолько, что его перестали читать целиком.
+- Планы лежат вперемешку: часть исполнена, часть нет, и по тексту это не различить.
+
+## Признак отбора — один, и он решается до первой правки
+
+**Утверждение остаётся в документе, если править его никто не собирается.** Всё остальное —
+работа, и её место в очереди работ.
+
+| Что нашлось                                             | Куда                                                            |
+| ------------------------------------------------------- | --------------------------------------------------------------- |
+| дыра, которую будут чинить                              | задача; строка из документа уходит                              |
+| дыра, которую решено не чинить                          | остаётся, вместе с причиной                                     |
+| условный отказ («заведём, если случай окажется частым») | остаётся                                                        |
+| вывод разбора, не ставший правилом                      | остаётся                                                        |
+| описание сделанного                                     | удаляется без переноса: о нём говорят закрытые задачи и история |
+| утверждение, разошедшееся с деревом                     | удаляется как протухшее, а не переносится в задачу              |
+
+Спрашивать владельца об этом наборе не нужно — он записан здесь. Спрашивать стоит одно: судьбу
+самого файла, когда в нём не осталось ничего.
+
+## Обход идёт по утверждениям, а не по пунктам
+
+Работа лежит и в прозе: раздел без единого маркера обход по списку не увидит вовсе. Абзац
+судится тем же признаком, что и пункт.
+
+## Номер задачи стоит в нескольких местах
+
+Прежде чем считать «пункты без задачи», надо знать все формы записи — в заголовке, отдельной
+строкой у раздела и в конце пункта. Разбор, знающий одну форму, ошибается молча. **Число,
+полученное разбором текста, сверяется на выборке руками до того, как его называют.**
+
+## Сверка с очередью работ
+
+У пункта есть задача — это ещё не значит, что задача несёт его содержание. Перед удалением
+меряется покрытие: сколько значимых слов пункта встречается в теле его задачи. Пункт, покрытый
+наполовину и меньше, читается глазами и разводится на три исхода:
+
+- живое уточнение, которого в задаче нет, — дописать в тело;
+- другой дефект — завести своей задачей;
+- протухшее — удалить, **не** перенося. Иначе разбор занесёт в задачу ложь.
+
+**Наследование номера от заголовка — предположение, а не факт.** Пункт под заголовком с
+несколькими номерами не принадлежит ни одному из них: привязка проверяется чтением.
+
+## Сделанность читается по дереву
+
+Утверждение о том, что задача не сделана, стареет так же, как любое другое. Проверяется то, о
+чём собираешься сказать «не сделано», — поиском по дереву, а не памятью.
+
+## Доводы за отсрочку — это «чего это стоит»
+
+Раздел «что стоит отложить» переезжает не в архив, а **в тела тех задач, которых он касается**:
+там он и есть оценка цены. В файле он остаётся, только если отсрочка — решение владельца, а не
+предложение разбора. Признак — записанный ответ владельца с датой.
+
+## Ссылки на снятые разделы
+
+Задача, чьё тело ссылается на раздел документа, после разбора ведёт в пустоту, и проверка путей
+этого не видит: она читает файлы репозитория, а не тела задач. Строка снимается тем же заходом.
+
+## Судьба файла
+
+- Осталось незадачное — файл живёт, и его вступление объявляет новый признак отбора.
+- Не осталось ничего, а документ описывал состоявшуюся работу — уезжает в архив.
+- Не осталось ничего, и это был список работ — удаляется.
+
+Разбор целиком — одна задача и одна ветка: делится то, что придётся откатывать порознь, а здесь
+откат общий. Правка кода, найденная по дороге, в эту ветку не идёт — иначе откат разбора унесёт
+починку.
+
+## Что чинится в дереве следом
+
+Документ — не единственное место, обещающее, что работа живёт в нём. Снятое имя вычищается одним
+проходом по всему дереву, включая описания ролей, скилы, README и комментарии в коде.
+
+## Частые промахи
+
+- Обход по маркированным пунктам: половина работы лежит прозой и переживает разбор.
+- «На это есть задача» без чтения её тела: пункт удалён, содержание потеряно.
+- Число пунктов названо владельцу до сверки на выборке.
+- Протухшее утверждение перенесено в задачу и стало действующим указанием.
+- Доводы за отсрочку оставлены в документе: он снова становится вторым списком работ.
+- Разбор поделён на несколько задач «по объёму» — признак деления не объём, а раздельный откат.
+- Архив тронут: он описывает состояние на момент написания и под новые термины не правится.

package/assets/patterns/doc-style-write.md

@@ -0,0 +1,106 @@
+---
+name: doc-style-write
+kind: pattern
+rule: doc-style
+description: Паттерн правила doc-style. Брать при написании любой прозы проекта — правил, спеков, README, комментариев в коде, тел коммитов, описаний PR. Примеры «так» и «не так» на каждую договорённость о формулировке. Не брать для устройства спека — это правило spec-driven.
+---
+
+# Как формулировать
+
+Паттерн правила `doc-style`. Что при этом должно быть верно — закон
+`{{lawsDir}}/project-documentation.md`.
+
+## Когда брать
+
+- Пишется правило, статья закона, пункт спека или README.
+- Пишется комментарий в коде, тело коммита, описание PR.
+
+## Статья — одна фраза
+
+Сама статья укладывается в одно предложение. Следом — не больше двух предложений о том, что
+сломается иначе, и только если из самой фразы это не видно. Обоснование, у которого была
+альтернатива, идёт в «Ловушки» правила, а не в закон: разросшийся пункт читают по диагонали, а
+закон говорит, что верно, — не почему когда-то выбрали так.
+
+```
+✗ **Взрослых в записи хотя бы один — на любом пути записи, без исключений.** Нижнюю
+  границу держит хранилище: путей записи три, и проверка в одном из них закрывает не все.
+  Верхнюю ограничением хранилища не выразить — она лежит в самой записи и меняется
+  владельцем.
+
+✓ **Взрослых в записи хотя бы один.** Исключений нет.
+✓ **Взрослые и дети не превышают вместимость.**
+```
+
+## Что верно, а не где это держится
+
+«Держит хранилище, а не служба», «проверяется в транзакции», «умолчание колонки», «на трёх
+путях записи из четырёх», имена функций и колонок внутри фразы — это устройство кода. Читателю
+нужно знать, **что** верно.
+
+Место исполнения меняется при первом же переносе, и документ, который его называет, устаревает
+молча. Для него заведён отдельный файл — `implementation.md` рядом с правилом.
+
+Исключение — «Ловушки» правила: там устройство кода называется прямо, потому что ловушка и есть
+место, где на него наступают.
+
+## Без утверждений о будущем
+
+«Не планируется», «не будет», «отдельная задача по запросу» — это намерение владельца, а не
+свойство системы. Что не сделано — да, почему не сделано — да, что не будет сделано никогда —
+нет.
+
+Ошибка беззвучная: сверять утверждение о будущем не с чем, оно проходит любую проверку.
+
+Отсюда же: того, чего нет в документе о продукте, пересказ не утверждает. Домысел при пересказе
+звучит убедительнее исходника — он короче и категоричнее.
+
+## Простыми словами
+
+Афоризмы, метафоры и инверсии затрудняют чтение и ничего не добавляют.
+
+```
+✗ запись о прошлом не должна упираться в правило, появившееся позже
+✗ пустой список без текста и отказ без кнопки выглядят одинаково — как сломанная страница
+
+✓ запись, внесённую владельцем, пропажа события из ленты не снимает
+✓ у пустого списка должен быть текст, у отказа — кнопка повтора
+```
+
+Проверка: прочитать фразу вслух. Если так не говорят — переписать.
+
+## Факт проверяется, а не вспоминается
+
+Перед тем как написать, что код делает то-то, — открыть код и посмотреть. Пересказ по памяти
+выглядит так же уверенно, как проверенное утверждение, и отличить их потом нечем.
+
+Особенно это касается отказов: недостижимый отказ, названный в документе, живёт там годами —
+проверить его читателю нечем.
+
+## Не пересказывать то, у чего есть источник
+
+- типы и поля контракта — ссылкой на сам контракт;
+- колонки и индексы — ссылкой на схему хранилища;
+- числа, которые правит владелец, — только как они применяются;
+- слои и имена классов — правило `lib-layers` и сам код.
+
+## Комментарии в коде
+
+Те же правила. Комментарий отвечает на вопрос «почему так, а не иначе» — если ответ неочевиден.
+Что делает строка, видно из строки.
+
+Многострочный комментарий над каждой функцией — признак того, что объяснение подменило имя.
+Сначала переименовать, потом писать комментарий.
+
+Комментарий, оправдывающий отклонение от правила, держит это отклонение на себе: пока
+объяснение выглядит убедительно, отклонение не трогают. Факт в нём проверяется, когда
+комментарий пишут, и перепроверяется, когда отклонение снимают.
+
+## Частые промахи
+
+- Чужой проект назван в коммите, PR, комментарии или документе. Ни имени репозитория, ни
+  «портировано из», ни ссылок на его файлы — нигде.
+- Число написано по памяти, а не пересчитано командой в том же коммите.
+- Пункт плана вычеркнут по памяти о работе, а не по дереву.
+- Формулировка звучит как заголовок, а не как статья: «работа со скидками» нарушить нельзя,
+  «применяется одна максимальная скидка» — можно.

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

@@ -0,0 +1,175 @@
+---
+name: git-workflow-commit
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит, пуш и создание PR — план до первой задачи, заведение задачи всеми шагами сразу, перевод по колонкам, слияние двух задач в одну, работа от учётной записи машинной работы, формат заголовка, строка связи с задачей, состав PR, чеклист проверок до публикации. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+---
+
+# Ветка, коммит и PR
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон `{{lawsDir}}/delivery.md`.
+
+## Когда брать
+
+- Заводится задача, с которой начинается правка.
+- Заводится ветка под задачу.
+- Готовится коммит или пуш.
+- Открывается PR.
+- Работа перешла на следующий шаг, и задача переставляется в другую колонку.
+
+## Сначала план, потом задачи
+
+Работа, из которой выходит больше одной задачи, начинается с плана, и план показывается
+владельцу до того, как заведена первая задача. Разбивка — решение о том, что делается и в каком
+порядке, и принимает его владелец, а не тот, кто заводит.
+
+Заведённые до согласования задачи стоят в очереди как решённое дело: они показывают работу,
+которую никто не заказывал, и убирать их потом дороже, чем не заводить.
+
+Признак тот же, что у деления на ветки, — раздельный откат. Один дефект планом не описывается:
+для него сразу заводится задача.
+
+Плана нет, а работа делится — сначала пишется план, показывается, и только после ответа
+владельца заводится первая задача. Ответ «делай» — тоже ответ; молчание им не является.
+
+## Сначала задача, потом ветка
+
+Заведение состоит из нескольких шагов: сама задача, номер в её заголовке, добавление в очередь,
+начальное состояние. Очередь к репозиторию обычно не привязана, поэтому добавление само не
+случается, и задача без него не видна ни в очереди, ни владельцу. Все шаги делает одна команда
+— не рука.
+
+Название задачи говорит, что не так, а не что сделать: PR потом переводит его в сделанное.
+Номер в заголовок руками не пишется — он известен только после создания.
+
+## Две задачи, которые чинятся одной правкой
+
+Если по ходу выяснилось, что правка закрывает и соседнюю задачу, — это одна задача, а не две.
+Слить их можно, пока правка не въехала в главную ветку: недостающее из поглощённой дописывается
+в тело первой, и только потом поглощённая закрывается и снимается с очереди. Порядок важен —
+удаление уносит с собой ссылки на неё из чужих тел.
+
+После слияния ветки поглощения нет: она въехала, и откатывается целиком.
+
+## Ветка заводится отдельным вызовом
+
+Гард главной ветки разбирает текст команды и смотрит ветку на момент запуска, поэтому составная
+команда отклоняется целиком — ветки в ней ещё нет:
+
+```bash
+✗ git checkout -b <ветка> && git commit -m '…'
+✓ git checkout -b <ветка>
+✓ git commit -F -
+```
+
+Имя ветки несёт номер задачи. Гард поставки разбирает его на месте и отбивает промах в форме до
+первого коммита, а по номеру спрашивает очередь: задача должна существовать, быть открытой,
+стоять в очереди и иметь исполнителя.
+
+Имя без номера законно, пока ветка живёт локально — под пробу и разбор. PR с неё не откроется:
+правка, доезжающая до главной ветки, начинается с задачи.
+
+## Колонка задачи двигается вместе с работой
+
+Ветка заведена — задача уже не в начальной колонке, а в работе. PR открыт — она ждёт разбора.
+Оба перевода делает одна команда, вторым вызовом сразу за тем, который его вызвал.
+
+Перевод не откладывается на потом: очередь читают между шагами, а не после них. Задача с
+открытым PR, простоявшая в начальной колонке, всё это время выглядела нетронутой — и разбора за
+неё никто не ждал.
+
+## Коммит подписывается учётной записью машинной работы
+
+Токен читается в переменную и не печатается; автор и коммиттер задаются переменными той же
+команды. Правка общей настройки здесь не годится — она переписала бы подпись владельцу:
+
+```bash
+TOKEN=$(tr -d '\n' < <файл с токеном>)
+
+GIT_AUTHOR_NAME="<бот>" GIT_AUTHOR_EMAIL="<адрес бота>" \
+GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<адрес бота>" \
+    git commit -F -
+```
+
+Заголовок — `тип(область): описание`, без точки в конце. Набор типов и областей задан
+настройкой проверки заголовка.
+
+## Документ едет тем же коммитом
+
+Гард документов требует пару и называет её сам. Обход — строка в теле коммита, причина
+обязательна:
+
+```
+Docs-skip: правка только в сценариях хука, зеркала у него нет
+```
+
+## Номер задачи стоит в её заголовке и в заголовке PR
+
+Форма одна на оба. Номер стоит в самом заголовке, а не только в теле: в списке PR тела не
+видно. Тот же номер несёт и имя ветки — поэтому задача, ветка и PR читаются как одно.
+
+Задача говорит, что не так; PR тем же номером отчитывается, что сделано. Инфинитив из задачи в
+заголовок PR не переносится: «исправить» становится «исправлено».
+
+Тип и область коммита в заголовок PR не идут: род правки и область уже видны метками.
+
+## PR прикрепляется к задаче
+
+Тело начинается со строки связи с задачей — по ней в очереди заполняется поле связанных PR.
+Ревьювер, исполнитель и метки задаются той же командой, и PR без них не открывается.
+
+Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Метки берутся
+у задачи целиком — и род правки, и все её области; читаются они у задачи, а не выбираются по
+памяти.
+
+Строка связи обязательна: без неё PR не прикрепляется к задаче. Она же означает, что задача
+закрывается целиком — половину задачи одним PR не выкатывают: у задачи одна ветка, и работа,
+которая в неё не влезает, делится на задачи до того, как ветка заводится.
+
+Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: отчёт утверждает
+про дерево, а дерево с тех пор изменилось.
+
+## Что проверяется до публикации PR
+
+Проверок на самом PR нет: выкатка запускается пушем в главную ветку, и до слияния никто не
+гоняет ничего. Линтеры и юниты снимает гейт пуша — ниже то, чего он не знает.
+
+1. **В ветке только та правка, за которой её заводили** — сводка расхождения с главной веткой.
+   Чужой домен в списке файлов означает, что правка расползлась.
+2. **Ни мока, ни подменённого ответа, ни отладочной строки** — расхождение читается целиком, а
+   не по именам файлов. На прод они уезжают молча и портят настоящие данные.
+3. **Документ едет тем же коммитом.** Пару называет гард, но спек домена и правку его поведения
+   он не знает — это остаётся за автором.
+4. **Проверки текстов и раскладки зелёные.**
+5. **Все приложения собираются.** Гейт пуша сборку обычно не гоняет.
+6. **Видимый текст заведён во всех локалях.**
+7. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
+   `browser-verification-measure`.
+8. **Правка публичной разметки проверена на прод-сборке по всем локалям** — паттерн
+   `seo-verify`.
+9. **Тело PR начинается строкой связи с задачей**, а метки, ревьювер и исполнитель стоят.
+10. **Заголовок PR несёт номер задачи и называет её сделанной** — тем же номером, что у задачи
+    и в имени ветки.
+11. **Очередь работ сходится.** Задача в очереди, с исполнителем и номером в заголовке; PR один
+    на задачу, и закрывает он её целиком.
+
+Сразу после публикации задача переставляется в разбор, и сверка очереди прогоняется ещё раз: до
+открытия PR колонку она не судит, а после открытия расхождение видит.
+
+Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное, названное
+проверенным, ревьювер принимает за проверенное.
+
+## Частые промахи
+
+- **Добавление в индекс нескольких путей не добавляет ничего, если хоть один путь не
+  существует.** Команда обрывается на первом промахе целиком, а следующая правка последнего
+  коммита уносит в него всё, что осталось в индексе. Состав коммита читается сразу после него,
+  а не на разборе PR.
+- **Задача, заведённая мимо команды, в очередь не попадает и гардом не отбивается** — он
+  смотрит команду, а не задачу. Ловится это только сверкой очереди.
+- **Исполнитель у задачи сам не проставляется** ни при заведении через веб, ни при добавлении в
+  очередь.
+- **Колонка сама не двигается** ни от заведения ветки, ни от открытия PR: очередь ветки не
+  видит вовсе, а связь с PR заполняет только поле связанных PR.
+- **Постраничный обход очереди через общий флаг уходит в повтор первой страницы** — курсор
+  берётся из ответа руками, а полнота сверяется с общим числом элементов.

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

@@ -0,0 +1,82 @@
+---
+name: git-workflow-merge
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать, когда главная ветка вливается в ветку задачи и разрешается конфликт — порядок слияния, разбор конфликта по роду файла, сверка дописанного веткой с очередью работ, проверки после разрешения, перечитывание тела уже открытого PR. Не брать для заведения ветки, коммита и PR — это паттерн git-workflow-commit.
+---
+
+# Вливание главной ветки в ветку задачи
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон `{{lawsDir}}/delivery.md`.
+
+## Когда брать
+
+- PR отмечен конфликтующим, и его надо вернуть к сливаемому состоянию.
+- Главная ветка ушла вперёд, и ветку задачи надо подтянуть до проверок.
+- Коммит переносится отдельным выбором.
+
+## Порядок
+
+```bash
+git fetch origin
+git merge origin/<главная ветка> --no-edit
+git diff --name-only --diff-filter=U     # что встало конфликтом
+```
+
+Список конфликтов читается целиком до первого разрешения: род файла решает приём, и разные
+файлы одного слияния разрешаются по-разному.
+
+| Что встало конфликтом | Как разрешается                                                                |
+| --------------------- | ------------------------------------------------------------------------------ |
+| код                   | ловушка правила `git-workflow` про сторону-удаление; после — проверка повторов |
+| спек домена           | сохранением обеих сторон — правило `spec-driven`; после — проверка спеков      |
+| накопительный список  | признаком отбора — паттерн `doc-style-sweep`                                   |
+
+## Что дописала ветка, видно только от точки расхождения
+
+Конфликтный маркер показывает место, а не правку: сторона ветки в нём — её допись вместе со
+всем, что лежало в файле до неё.
+
+```bash
+git diff "$(git merge-base origin/<главная ветка> HEAD)" HEAD -- <файл>
+```
+
+## Дописанное веткой сверяется с очередью работ, а не переносится по умолчанию
+
+Раздел, который ветка дописала в накопительный список, к моменту слияния обычно уже стоит
+задачей: ветка живёт неделями, а замеченный по ходу дефект заводится задачей сразу. Перенести
+его второй раз — завести вторую запись об одной работе.
+
+Когда задача несёт то же содержание, сторона ветки не переносится:
+
+```bash
+git checkout --theirs <файл> && git add <файл>
+```
+
+При слиянии `--theirs` — влитая главная ветка, а `--ours` — ветка задачи; при перебазировании
+стороны меняются местами. Взятая не та сторона стирает работу молча.
+
+## Проверки после разрешения
+
+Конфликт в текстах кода не задевает, и зелёная сборка про него ничего не говорит:
+
+```bash
+grep -rn '^<<<<<<< \|^>>>>>>> ' --exclude-dir=node_modules --exclude-dir=.git .
+```
+
+Следом гоняются проверки текстов, раскладки, повторов и очереди работ, а если конфликт задел
+хуки — их сценарии. Коммит слияния подписывается так же, как любой другой, — паттерн
+`git-workflow-commit`. После пуша состояние читается у самого PR, а не по своему дереву.
+
+## Тело открытого PR перечитывается после слияния
+
+Отчёт описывал дерево на день, когда его написали. Вливание главной ветки меняет то, о чём он
+утверждает: тело говорит про записи, которые главная ветка к тому времени уже разобрала.
+
+## Частые промахи
+
+- «Сохранить обе стороны» применено ко всем файлам одинаково: в спеке это верно, в коде и в
+  накопительном списке — нет.
+- Сторона ветки перенесена без сверки с очередью работ: одна работа стала двумя записями.
+- После разрешения прогнана сборка, а проверки текстов — нет: конфликта в них сборке не видно.
+- Тело PR оставлено прежним: ревьювер читает утверждение о дереве, которого больше нет.

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

@@ -0,0 +1,58 @@
+---
+name: git-workflow-migration
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при правке схемы хранилища и каталога миграций — прогон цепочки на одноразовом хранилище, написание файла миграции разницей, догон локального хранилища. Не брать для коммита и PR — это паттерн git-workflow-commit.
+---
+
+# Миграция и прогон цепочки
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон `{{lawsDir}}/delivery.md`.
+
+## Когда брать
+
+- Правится схема хранилища.
+- Заводится или переименовывается каталог миграции.
+- Ветка с новой миграцией готовится к слиянию.
+
+## Цепочка гоняется на одноразовом хранилище
+
+Линтеры, тесты и сборки порядок миграций не трогают вовсе, а проверка соответствия схемы идёт
+уже после слияния. Поэтому ветка прогоняется до слияния на пустом хранилище:
+
+```bash
+docker run -d --rm --name <проба> -e <пароль> -p <порт>:<порт> <образ хранилища>
+docker exec <проба> <проверка готовности>   # накат до готовности падает на соединении
+<адрес хранилища> npx <инструмент> migrate deploy
+<адрес хранилища> npx <инструмент> migrate diff --from-config-datasource --to-schema <схема> --exit-code
+docker stop <проба>
+```
+
+Одноразовое хранилище, а не своё: гард запросов отбивает схемные команды, и завести базу под
+проверку иначе нечем. Адрес ставится префиксом самой команды — экспорт между вызовами не живёт.
+
+## Файл миграции пишется тем же хранилищем
+
+Команда разработчика для миграций не запускается: любое расхождение состояния она лечит
+предложением сбросить хранилище, а в локальном лежат данные владельца. Файл берётся разницей
+между накатанной цепочкой и схемой.
+
+Каталог заводится **после** наката цепочки: пустой каталог, попавший в накат, помечается
+применённым, и его содержимое на это хранилище уже не встанет.
+
+## Локальное хранилище догоняет ветку
+
+Переименованная миграция остаётся в нём под прежним именем, и накат падает на «объект уже
+существует». Состояние правится отметкой о применении, повторный накат его не чинит.
+
+## Частые промахи
+
+- Метку времени ставит момент создания, а порядок применения лексикографический: миграция из
+  ветки, начатой раньше, встаёт перед той, от которой зависит. На существующем хранилище это
+  незаметно — падает только накат с нуля.
+- Флаги инструмента не те, что в примерах из сети, и на неизвестный флаг он печатает справку, а
+  не строку ошибки. Какие флаги есть сейчас, смотрят в его собственной справке.
+- Запись в боевое хранилище запрещена совсем: схема меняется миграцией через выкатку, данные —
+  через интерфейс.
+- Строки адресуются по первичному ключу, а не по маске: удаление по маске уносит вместе с
+  пробными записями настоящие.

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

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