@rt-tools/agent-kit 0.5.2 → 0.6.0

package/assets/laws/observability.md

@@ -0,0 +1,46 @@
+# Закон о наблюдаемости
+
+Что владелец знает о работе своего приложения. Если о поломке можно узнать только через доступ
+к серверу, владелец узнаёт о ней от гостя и с опозданием.
+
+**Ревизия:** 2026-08-13
+
+## Статьи
+
+- **Отказ приложения виден владельцу без доступа к серверу.** На сервер владелец не заходит,
+  поэтому всё, что видно только оттуда, для него недоступно.
+- **Отказ хранится и после перезапуска приложения, и спустя месяцы.** Поломку разбирают уже
+  после того, как она случилась, а вывод приложения к этому времени затирается.
+- **Все отказы одного обращения находятся по одному признаку.** При десятке обращений в секунду
+  по времени их не разделить.
+- **Тот, кто наткнулся на отказ, получает номер обращения и может его назвать.** Иначе по жалобе
+  нечего искать.
+- **Наружу уходит номер обращения и общий текст ошибки. Подробности остаются внутри.**
+  Подробности показывают, как приложение устроено.
+- **Подробности отказа закрыты правом.** В них видно, кто был в системе и чем именно приложение
+  сломалось.
+- **Владелец узнаёт о новом отказе сам, без захода на экран.** Иначе поломку заметят только
+  тогда, когда до экрана дойдут руки.
+- **У обращения к чужой службе есть предел ожидания.** Молчащая служба отличается от отказавшей
+  только временем: без предела обращение висит до умолчания среды, отказ не наступает вовсе, и
+  записывать нечего. Всё это время владелец видит исправную работу.
+- **Обращение к чужой службе оставляет запись, и заводится она до обращения.** Запись после
+  ответа говорит только о том, что дошло: попытка, оборвавшаяся посередине, не отличается от не
+  начатой, а владелец видит лишь удачные исходы.
+- **Отказ не записывается в ущерб работе приложения.** Ответ не ждёт записи, запрос из-за неё не
+  падает. Если записать не удалось, это видно.
+- **Приложение не пишет отказы о собственной записи отказов.** Иначе поломка хранилища порождает
+  поток, который сам себя разгоняет.
+- **Отказом считается то, что не сработало, а не каждый обслуженный запрос.** Иначе поток чужих
+  обращений определяет, сколько приложение о себе хранит.
+- **У хранилища отказов есть предел, и он проверяется до того, как кончится место.** Иначе
+  хранилище отказов положит приложение, за которым следит.
+- **Секреты и личные данные вычищаются перед записью.** После записи их убирают правкой данных,
+  а это дороже и не всегда возможно.
+
+## Открытые вопросы
+
+- **Q-O-1.** Куда девать отказ, случившийся до того, как приложение поднялось. Хранилища в этот
+  момент ещё нет. Сейчас такой отказ остаётся только в выводе приложения.
+- **Q-O-2.** Хранить ли отказы обвязки — того, что стоит перед приложением и отдаёт страницы.
+  Её вывод к приложению не приходит, и читать его надо отдельно.

package/assets/laws/project-documentation.md

@@ -33,6 +33,10 @@
   — это намерение, а не свойство приложения: сверить его не с чем, и оно проходит любую
   проверку. Машине это не поручить: открытый вопрос пишется теми же словами, что и обещание,
   и проверка отбивала бы оба.
+- **Полнота текстов проверяется и со стороны работы, а не только со стороны текста.** Обход
+  написанного судит каждое утверждение, но утверждения, которого нет, в этом обходе нет тоже:
+  приём, применённый и нигде не описанный, так не находится никогда. Поэтому закрытая работа
+  спрашивается отдельно — оставила она след в текстах или явно его не требует.
 - **Документ утверждает о состоявшемся, а не о том, что должно сработать.** Лечение,
   записанное готовым до того, как его прогнали, дороже отсутствия записи: следующий читатель
   берёт его за проверенное — и берёт в тот день, когда лечение понадобилось, а времени на

package/assets/laws/reuse-first.md

@@ -8,6 +8,8 @@
 
 ## Статьи
 
+- **У каждого приложения один источник вида, и он у них разный.** Взять контрол из чужого
+  источника значит принести на экран форму, которой в этом приложении нет больше нигде.
 - **Готовое берут, а не пишут заново.** Своя копия расходится с оригиналом с первой же правки,
   и одинаковые с виду места начинают вести себя по-разному.
 - **Отойти от общего вида может решить только владелец.** Сделать своё вместо готового

package/assets/laws/verifiability.md

@@ -56,3 +56,8 @@
   род события и версия одинаковы везде, где стоит слой правил; путь, домен и имя дерева
   принадлежат одному дереву и в чужом месте не значат ничего, кроме утечки. Держится это
   проверкой на выносящей стороне, а не памятью того, кто пишет.
+- **Проверка, которая сама сломалась, работу не останавливает.** Отказ инструмента не является
+  найденным нарушением, и остановленная им работа стоит до того, как его починят.
+- **Решение, зависящее от текущего момента, получает момент снаружи.** Иначе проверить его можно
+  только подкруткой часов, а подкрученные часы действуют и на всё, что оказалось рядом: проверка
+  начинает зависеть от того, что к ней отношения не имеет.

package/assets/patterns/browser-verification-stand.md

@@ -50,12 +50,12 @@ npx nx build admin --base-href=/
 Angular DevTools, нужна ещё и dev-конфигурация (`--configuration=development`): прод-сборка не
 публикует `window.ng`. Выводы о размере бандла и минификации на такой сборке делать нельзя.
 
-Сессия кладётся в `localStorage['vm.admin.token']` **строкой JSON** (`JSON.stringify(token)`),
+Сессия кладётся в `localStorage['<ключ сессии админки>']` **строкой JSON** (`JSON.stringify(token)`),
 иначе приложение её не прочитает. Токен не подписывается руками, а берётся у живого API:
 `POST /<область>.v1.AuthService/Login`. Команду с паролем классификатор блокирует — обходить не
 надо, спрашивать разрешение у владельца.
 
-Взять уже открытую сессию нельзя: чтение `localStorage['vm.admin.token']` из браузера
+Взять уже открытую сессию нельзя: чтение того же ключа из браузера
 блокируется. Оба пути к своему стенду упираются в пароль, поэтому остаётся третий — смотреть
 на админке владельца, где вход уже сделан. Свой стенд нужен, только когда проверяют
 прод-сборку, `--base-href` или конфиг nginx; чтобы просто посмотреть экраны, он не нужен.
@@ -131,8 +131,28 @@ pnpm install --frozen-lockfile         # из ../<префикс>-base: node_mod
 - Оба стенда держат поднятыми одновременно: если сравнивать по памяти между двумя запусками,
   заметишь только то, что успел запомнить.
 
+## Состояние портов снимается до первой сборки захода
+
+Серверы владельца ложатся и без твоего участия: сайт отдавал 404 на все свои адреса ещё до
+первой сборки захода, а API замолчало посреди него. Без замера «до» падение нельзя ни
+приписать своей сборке, ни снять с неё подозрение.
+
+```bash
+for u in http://localhost:{{apiPort}}/health http://localhost:{{sitePort}}/ http://localhost:{{adminPort}}/; do
+    printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$u")" "$u"
+done
+```
+
+Замер — это ответ, а не `lsof`: порт бывает занят собранным артефактом прошлой сессии, и он
+отвечает 200 старым кодом.
+
 ## Частые промахи
 
+- **Одиночная сборка проекта серверы переживают, и отказываться от неё незачем.** Замерено
+  ответом до и после: все порты остались за своими процессами. Осторожность здесь стоит дороже
+  проверки — целая команда паттерна `seo-verify` осталась незапущенной ровно потому, что сборку
+  сочли опасной, не замерив. Сборка из кэша замером не является: она не собирает вовсе, и видно
+  это по её длительности.
 - Свой дев-сервер не поднимать: сайт на {{sitePort}}, админка на {{adminPort}}, API на {{apiPort}} уже подняты
   владельцем, и второй экземпляр отбивается гардом.
 - **Общая сборка глушит все три дев-сервера владельца, а не только API.** После

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

@@ -0,0 +1,111 @@
+---
+name: doc-style-trace
+kind: pattern
+rule: doc-style
+description: Паттерн правила doc-style. Брать, когда полнота текстов проверяется со стороны работы, а не со стороны текста — обратный проход по закрытым задачам: признак отбора машиной, чего он не видит, три исхода по каждой задаче, граница «код не правится». Не брать для разбора документа, накопившего список работ, — это паттерн doc-style-sweep.
+---
+
+# Обратный проход: закрытые задачи против текстов
+
+Паттерн правила `doc-style`. Что при этом должно быть верно — закон
+`docs/constitution/project-documentation.md`.
+
+## Когда брать
+
+- Проверяется не то, верен ли текст, а то, есть ли он вообще.
+- Разбирается работа, закрытая до того, как в закрытие задачи вошёл шаг приведения текстов.
+- Волна разбора со стороны текста кончилась, а находок в ней вышло мало.
+
+## Проход со стороны текста не находит того, чего не написали
+
+Он читает написанное и судит каждое утверждение; утверждения, которого нет, в обходе нет
+тоже. Со стороны работы находок на порядок больше: в первой части семь находок из восьми
+легли туда, где текста не было вовсе, а не туда, где он устарел.
+
+## Признак отбора — ветка внесла код и не тронула ни одного текста
+
+Отбирается машиной и чтения не требует. Что ветка внесла на самом деле, отвечает история, а
+не папка задачи: папка разбирается при закрытии, и таблица следа задачи до главной ветки не
+доезжает вовсе.
+
+```bash
+git log --merges --format='%H %s' <главная ветка> | grep -E 'from [^/]+/<ключ задач>-[0-9]+-'
+git diff --name-only <мерж>^1 <мерж>
+```
+
+Признак считается вычитанием, а не двумя списками путей: код — всё, что не `.md`, текст —
+любой `.md` вне описания прошлого и папок задач. Списки, написанные руками, разошлись по обоим
+краям сразу, и разошлись молча.
+
+Список текстов пропустил самые читаемые тексты дерева: тот, что приходит в контекст каждой
+сессии целиком, и тот, что описывает устройство дерева. Три задачи, тронувшие ровно их, попали
+в выборку как бесследные — и во вторую часть прохода попали второй раз, уже как тронувшие
+текст.
+
+Список кода пропустил обвязку: гарды, конвейер и файлы выкатки в нём не значились, и две
+задачи, правившие только их, не попали ни в одну выборку вовсе. Нашлись они не признаком, а
+сверкой двух выборок между собой — её и стоит прогнать перед каждой следующей частью:
+
+```bash
+comm -23 <список бесследных> <разобранные первой частью>       # кого не прочитал никто
+comm -12 <разобранные первой частью> <список тронувших текст>  # кого прочитали дважды
+```
+
+## Часть назначает самая узкая область задачи, и метки бывает нет вовсе
+
+Выборка, которую признак отобрал, одним заходом не читается, и делится она по области —
+метке области у задачи. Меток у задачи бывает несколько; часть назначает самая узкая из них, а
+порядок сужения выбирается один раз на весь проход и записывается в замысел вместе с таблицей
+частей. При обратном порядке самые широкие области забрали бы себе все спорные задачи, и у
+узких не осталось бы почти ничего.
+
+Задача без единой метки области не попадает ни в одну часть вовсе — ни по какому порядку
+сужения. Признак её отобрал, читать её некому, и видно это только пересчётом:
+
+```bash
+awk -F'\t' 'NR==FNR{k[$1]=1;next} k[$1] && $2==""{print}' <номера выборки> <задачи с метками>
+```
+
+Такую задачу относят к части по предмету руками, и это решение записывается в разбор: иначе
+следующая часть пересчитает выборку и найдёт её снова непрочитанной.
+
+## Исходов у задачи три, а не два
+
+| Исход            | Признак                                                                                                   |
+| ---------------- | --------------------------------------------------------------------------------------------------------- |
+| следа не требует | приём нигде не повторён: вёрстка своего экрана, разовая правка по просьбе владельца                       |
+| след есть        | утверждение о работе стоит в правиле, паттерне или спеке — в том числе внесённое отдельной задачей следом |
+| следа нет        | приём применён и нигде не описан — это и есть находка                                                     |
+
+Приём, записанный отдельной задачей следом, промахом не является: работа сделана одной
+задачей, запись приёма заведена другой, и в очереди работ видны обе. Отличается это чтением
+соседних по времени задач той же области, а не признаком.
+
+Худшего случая признак не видит вовсе: ветка тронула соседний текст и обошла тот, который
+описывает её собственную работу. Такие задачи остаются следующей части прохода.
+
+## Граница «код не правится» и её единственное исключение
+
+Нашлось место, где неправ код, — заводится задача, проход идёт дальше. Кодом при этом не
+считается то, что описывает сверяемое правило: комментарий в шапке проверки и заголовок
+теста. Заголовок несёт идентификатор сценария, и без него новый сценарий значится непокрытым
+при живом тесте.
+
+## Находка кладётся в тот слой, которому принадлежит
+
+- приём повторён и решается в коде — утверждение правила с привязкой в именах дерева;
+- готовый код и порядок действий — паттерн;
+- обещание, которое видит человек, — сценарий спека домена с прежней нумерацией;
+- расхождение с договорённостью — текст статьи владельцу, файл закона не правится.
+
+## Частые промахи
+
+- Состав части взят из прошлого захода, а не пересчитан признаком. Выборки живут в
+  скретчпаде сессии и умирают вместе с ней; в дерево они не кладутся — деление на части
+  свойство прохода, а не продукта. Пересчёт стоит двух команд выше и даёт тот же список, а
+  состав, принятый на слово, нечем сверить с соседними частями — именно сверкой находятся те,
+  кого не прочитал никто.
+- Задача судится по своей папке: её разобрали при закрытии, и следа там не осталось.
+- «След есть» по одному упоминанию: упоминание в соседнем правиле приёма не описывает.
+- Находка записана только в паттерн: правило читают перед каждой правкой, паттерн — по имени.
+- Признак пересчитан на новом списке путей без сверки на выборке руками.

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

@@ -168,7 +168,7 @@ PR      [<КЛЮЧ>-86] Письмо владельцу с незаполнен
 задача  [<КЛЮЧ>-101] Вернуть оверлей загрузки таблицы и включить stylelint гейтом
 PR      [<КЛЮЧ>-101] Stylelint включён гейтом
 
-задача  [<КЛЮЧ>-212] Сайт не собирается: компонентам кита проставлен префикс vm- вместо rt-
+задача  [<КЛЮЧ>-212] Сайт не собирается: компонентам кита проставлен префикс приложения вместо своего
 PR      [<КЛЮЧ>-212] Виджет переписки зовёт кит его собственными именами
 ```
 

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

@@ -0,0 +1,203 @@
+---
+name: git-workflow-docker
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при работе с образами на своей машине — подъём и перезапуск демона, диагностика «висящей» команды, сборка под платформу прод-сервера, одноразовый контейнер рядом с чужими, вход в реестр из службы. Не брать для команд прод-сервера и выбора образа — это паттерн git-workflow-restart, и не для наката миграций — это git-workflow-migration.
+---
+
+# Образы на своей машине
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+Демон здесь чужой: на машине владельца в нём живут его хранилище разработки, его стенд и
+контейнеры других его работ. Любая команда пишется так, чтобы её отменяли, не спрашивая
+владельца, и чтобы она не задела ничего, кроме заведённого ею самой.
+
+## Когда брать
+
+- Команда демона не отвечает, и надо понять почему.
+- Нужен одноразовый контейнер рядом с уже работающими.
+- Собирается образ, который поедет на прод-сервер.
+- Раннер конвейера на этой машине не может войти в реестр.
+
+## Чужое не трогается
+
+Перед любым действием, которое задевает демон целиком, читается, что в нём живёт и переживёт
+ли оно перезапуск:
+
+```bash
+docker ps --format '{{.Names}} | {{.Image}} | {{.Status}}'
+docker inspect <контейнер> --format '{{.Name}} restart={{.HostConfig.RestartPolicy.Name}}'
+```
+
+`unless-stopped` поднимется сам, `no` — нет, и его возвращают руками сразу после подъёма
+демона. Стенд владельца обычно заведён с `no`: после перезапуска он остаётся лежать, а по его
+порту отвечает пустота — это выглядит поломкой стенда, а не следом перезапуска.
+
+Свои контейнеры именуются приставкой и снимаются по имени. `docker system prune`, `docker rm`
+по маске и `docker volume prune` не пишутся никогда: они уносят чужое молча.
+
+```bash
+docker rm -f <приставка>-ci-db >/dev/null 2>&1 || true   # снять прошлый прогон
+```
+
+Порт своего контейнера выбирается свободным: порт хранилища разработки занят, и попасть в него
+чужой миграцией нельзя.
+
+```bash
+lsof -nP -iTCP:<свободный порт> -sTCP:LISTEN     # пусто — порт свободен
+```
+
+## Место спрашивается до прогона
+
+Диск виртуальной машины отдельный от диска хоста: на хосте свободно, внутри пусто, и видно это
+только изнутри.
+
+```bash
+docker system df                       # образы, тома и кэш сборки с долей многоразового
+docker run --rm alpine:3 df -h /       # сколько осталось у самой виртуальной машины
+```
+
+Наружу нехватка выходит чужим лицом: контейнер поднимается и сразу гаснет, сверка схемы
+отвечает про ненакатываемую цепочку, гейт пуша краснеет целиком. По этим признакам чинят
+репозиторий, а причина в машине, — поэтому первое при любом из них `docker system df`.
+
+Освобождают отбором, а не общей чисткой: у сценария чистки образов сперва спрашивают, что он
+снял бы, и только потом дают снимать.
+
+## Демон поднимается своим CLI
+
+Открытие приложения виртуальную машину не поднимает: приложение считается запущенным, а демон
+не отвечает часами. Поднимает только собственная команда клиента, а готовность проверяется
+самим демоном:
+
+```bash
+docker desktop restart
+until docker info >/dev/null 2>&1; do sleep 5; done
+docker version --format 'демон: {{.Server.Version}}'
+```
+
+Состояние, которое печатает приложение, говорит про приложение: оно отвечает «работает» и
+тогда, когда демон не принимает ни одной команды. Единственный признак живого демона — ответ
+`docker info`. Первые полминуты после подъёма он отвечает ошибкой и пишет в лог, что маршрута
+до виртуальной машины нет: это нормальный старт, а не поломка.
+
+## «Команда висит» — сначала проверяется, вправду ли висит
+
+Вывод не заворачивается в `tail`, `head` и не глушится тихим режимом: они держат его в буфере
+до конца команды, и идущая работа выглядит зависшей. Читается прямой вывод:
+
+```bash
+docker pull alpine:3            # прогресс виден построчно
+```
+
+Скачивания не запускаются параллельно. Несколько одновременных забивают канал друг другу:
+образ, который тянется за три секунды, шёл полчаса — и это выглядело сломанным демоном, а было
+очередью, устроенной проверяющим.
+
+## Где рвётся: три яруса
+
+Ярусы проверяются по отдельности, иначе чинится не то. Каждый отвечает секундами:
+
+```bash
+# 1. Сеть машины: реестр отдаёт манифест
+curl -s -m 30 -w '%{http_code} за %{time_total}s\n' -o /dev/null '<адрес токена реестра>'
+
+# 2. Сеть контейнеров: объём проходит внутрь
+docker run --rm alpine:3 sh -c 'time wget -q -O /dev/null <адрес пробы канала>'
+
+# 3. Демон: тянет ли он сам
+docker pull busybox:latest
+```
+
+Хост тянет быстро, контейнер тянет быстро, а скачивание стоит — дело в демоне, и его
+перезапускают. Стоят все три — дело в сети машины, и демон ни при чём. Что делал сам демон,
+отвечают его логи: ходы к реестру, подъём и состояние, консоль виртуальной машины — три разных
+файла в каталоге данных клиента.
+
+## Команда из службы: свой каталог настроек и явный адрес демона
+
+Раннер конвейера запущен службой, и вход в реестр из неё отказывает: пароль сохраняет
+системный помощник хранения ключей, а сеанса пользователя у службы нет. Свой каталог настроек
+с пустым помощником от этого не спасает — клиент подставляет помощника сам и переписывает
+пустое значение молча. Поэтому вход не зовётся вовсе, а пароль пишется в файл настроек прямо:
+
+```bash
+export DOCKER_CONFIG="$(mktemp -d)"
+export DOCKER_HOST="unix://${HOME}/.docker/run/docker.sock"
+auth=$(printf '%s:%s' "${REGISTRY_USER}" "${REGISTRY_TOKEN}" | base64)
+printf '{"auths":{"<реестр>":{"auth":"%s"}}}' "${auth}" > "${DOCKER_CONFIG}/config.json"
+chmod 600 "${DOCKER_CONFIG}/config.json"
+```
+
+`DOCKER_HOST` здесь не для красоты: свой каталог уносит с собой и текущий контекст, а без него
+клиент идёт в общесистемный сокет, которого на машине с настольным клиентом нет вовсе, и
+отвечает «нет такого файла» на что угодно. Связь проверяется до сборки:
+
+```bash
+docker info --format 'демон: {{.ServerVersion}}'
+```
+
+Поле у `docker info` называется иначе, чем у `docker version`: имя из второй команды первая не
+понимает, и связь выглядит непроверенной, хотя демон отвечает.
+
+Что пароль принят, видно по ответу реестра: анонимному он отвечает `401`, авторизованному —
+содержимым или `403`, но не `401`. Каталог снимается в конце — раннер живёт между прогонами, и
+пароль реестра остался бы лежать на диске владельца.
+
+## Образ собирается под платформу прод-сервера
+
+Машина владельца и прод-сервер бывают разной архитектуры. Без явной платформы собирается образ
+под сборщика: он уходит в реестр, оттуда на сервер и не стартует там вовсе.
+
+```bash
+docker buildx build --platform <платформа сервера> -f <файл сборки> --output type=cacheonly .
+```
+
+`--output type=cacheonly` считает сборку, ничего не сохраняя, — этим замеряют время, не
+засоряя машину образом. Чужая платформа идёт эмуляцией, поэтому время сборки на машине и в
+облаке сравнивают числом, а не ожиданием.
+
+Сборщик с драйвером `docker-container` нужен для чужой платформы и заводится отдельно; его
+первый подъём тянет свой образ из реестра:
+
+```bash
+docker buildx create --name <приставка>-ci-builder --driver docker-container
+docker buildx inspect <приставка>-ci-builder --bootstrap    # покажет платформы и состояние
+docker buildx build --builder <приставка>-ci-builder …      # сборщик владельца не переключается
+```
+
+Сборщик не сносится после прогона: в его кэше живут слои и хранилище пакетов, а без них
+следующая сборка тянет все зависимости заново. Флаг `--use` тоже не пишется — он переключает
+сборщик владельца; вместо него `--builder` у самой сборки. Объявления сборщиков лежат в
+каталоге настроек, поэтому под своим каталогом их не видно вовсе — оставить их на месте
+помогает `BUILDX_CONFIG` с адресом каталога владельца.
+
+Установка зависимостей внутри сборки ограничивается по числу запросов, иначе она роняет сборку
+целиком — и не потому, что канал медленный, а потому, что сотни запросов забивают его сами
+себе.
+
+## Частые промахи
+
+- **Перезапуск демона объявлен сделанным по состоянию приложения.** Приложение говорит
+  «работает», а `docker info` в это же время отвечает ошибкой.
+- **Стенд не возвращён после перезапуска.** У него политика `no`, и владелец находит мёртвый
+  порт вместо стенда.
+- **Вывод команды заведён в `tail`** — и работающая команда объявлена зависшей.
+- **Несколько скачиваний разом** — и медленной объявлена машина, а не собственная очередь.
+- **Образ собран без указания платформы** — прод получает образ чужой архитектуры, и видно это
+  только на перезапуске контейнеров.
+- **Свой контейнер занял порт хранилища разработки** — конвейер пишет в данные владельца.
+- **Вход в реестр из службы сделан командой входа** — пароль уходит в помощник хранения ключей
+  даже из своего каталога настроек, и задание падает до сборки.
+- **Каталог настроек подменён, а адрес демона не задан** — и починка входа в реестр выглядит
+  как упавший демон.
+- **Сборщик снесён после прогона** — вместе с кэшем, и следующая сборка идёт как первая.
+- **Общая чистка ради места** — уносит чужие образы и тома, и восстановить их нечем.
+- **Место освобождено сценарием выкатки целиком.** Сценарий писан для прод-сервера: там
+  собирает конвейер, а сервер только тянет готовое, поэтому последним шагом сценарий сносит
+  кэш сборщика. На машине владельца собирает раннер, и тот же шаг оставляет сборщика без кэша.
+  Отбор самих образов у сценария годится и здесь — он идёт по имени своего реестра, оставляет
+  три последних sha и обходит поднятые контейнеры, — а вот его хвост на этой машине запускают,
+  только когда согласились ждать полную сборку.

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

@@ -0,0 +1,93 @@
+---
+name: git-workflow-secrets
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать при работе с ключами внешних служб — где они лежат, чем ключ, заводимый владельцем, отличается от ключа окружения, что означает каждое состояние строки интеграции и почему зелёная проба не обещает работающей возможности. Не брать для перезапуска прода и выбора образа — это паттерн git-workflow-restart.
+---
+
+# Ключи внешних служб
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Возможность, которая ходит наружу, молчит: не уходят письма, не обновляются переводы.
+- Заводится или меняется ключ внешней службы.
+- Разбирается, что именно выкачено и чего приложению не хватает для работы, — включая ключ,
+  который живёт в окружении и экрана не имеет.
+
+## Ключ, заводимый владельцем, живёт в хранилище, а не в окружении
+
+Такой ключ лежит строкой в хранилище, зашифрованной ключом шифрования секретов; рядом открытая
+подсказка из последних знаков и исход последней пробы. Читает его одна служба и отдаёт тем, кто
+ходит наружу.
+
+**Запасного пути на окружение нет.** Одноимённая переменная в составе прода ничего не значит:
+приложение её не читает. Из окружения берётся один ключ — тот, которым шифруются все
+остальные. Его потеря делает записанные ключи нечитаемыми, и заводить их заново бесполезно,
+пока он не вернётся.
+
+Заводит такие ключи владелец сам, экраном интеграций. **Агент ключи не вводит:** ввод ключа
+доступа в поле ему запрещён независимо от того, кто просит.
+
+## Не всякий ключ внешней службы заводится владельцем
+
+В хранилище живут ключи, которые владелец заводит сам и по-разному у каждого владения. Ключ,
+одинаковый для всего приложения, остаётся в окружении, и экрана интеграций у него нет.
+
+Половины такой пары — ключ бэкенда и ключ, вшитый в сборку, — лежат по разные стороны
+поставки, и заполнить можно ровно одну. Тогда возможность не выключена и не включена: виджет
+не рисуется, сервер ждёт токен. Приложение называет такое состояние сломанным и говорит о нём
+строкой лога и сводкой старта — что в ней стоит, описывает правило `observability`.
+
+Отсюда порядок разбора для ключа из окружения: он читается не экраном интеграций, а сводкой
+старта в логах контейнера — в каком из её списков стоит имя возможности.
+
+## Строка интеграции говорит пятью состояниями
+
+Порядок разбора важен — состояние хранилища перекрывает всё остальное:
+
+| Что показано                         | Что это значит                                                         |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| состояние неизвестно                 | ответ ещё не пришёл; утверждать нечего                                 |
+| хранилище недоступно                 | ключа шифрования нет; заводить ключи нельзя, и владелец тут ни при чём |
+| не задан                             | строки секрета нет вовсе — ключ никогда не заводили                    |
+| расшифровать нечем                   | строка есть, а ключ шифрования сменился; заводить заново бесполезно    |
+| не проверен · работает · не работает | ключ записан; дальше судит проба                                       |
+
+Отсюда короткий путь разбора: молчит письмо или перевод — сначала открыть этот экран, а не
+логи. «Не задан» отвечает на вопрос целиком, и десять дней молчащей почты выяснились именно
+им, а не сервером.
+
+## Зелёная проба обещает меньше, чем кажется
+
+Проба спрашивает у службы то, что та отдаёт по ключу: список доменов, список моделей. Ни
+письма, ни запроса за деньги она не делает — но и работоспособности возможности не доказывает:
+
+- список моделей отдаётся и при пустом балансе, а сам запрос отвечает отказом по деньгам.
+  Строка при этом зелёная;
+- проба почты сверяет адрес отправителя со списком подтверждённых — но только если адрес уже
+  заполнен. При пустом адресе она отвечает «работает», а письма не уйдут.
+
+Поэтому после ввода ключа проверяется сама возможность, а не строка: сохранить запись и
+убедиться, что предупреждение не пришло; дождаться первого обращения и увидеть письмо.
+
+## Переезд ключа из окружения в хранилище не делается миграцией
+
+Секрет шифруется приложением, поэтому запросом к хранилищу его не перенести: миграция заводит
+таблицу и не трогает значения. Ключ, переведённый из окружения в настройки, обязан быть
+заведён владельцем в тот же день, что выкачена правка, — иначе возможность замолкает молча.
+Сверяется тем же экраном интеграций сразу после выкатки.
+
+## Частые промахи
+
+- **Искать ключ поиском по составу прода и делать вывод.** Значение там лежит, приложение его
+  не читает, а хвост из последних знаков совпадает с записанным в хранилище — совпадение
+  подсказки и переменной ничего не доказывает, кроме того, что владелец завёл тот же ключ.
+- **Идти в логи прежде экрана.** Логи скажут про отказ внешней службы, а экран — «не задан»;
+  второе точнее и стоит одного нажатия.
+- **Считать отсутствие ошибок признаком работы.** Ни почта, ни перевод не роняют запрос:
+  обращение сохранится, запись сохранится, а наружу ничего не уйдёт.
+- **Заводить ключ заново при «расшифровать нечем».** Это не про ключ, а про ключ шифрования;
+  новый ляжет рядом и тоже не прочитается.