@rt-tools/agent-kit 0.22.0 → 0.24.0

package/assets/patterns/autonomous-work-run.md

@@ -0,0 +1,105 @@
+---
+name: autonomous-work-run
+kind: pattern
+rule: autonomous-work
+description: Паттерн правила autonomous-work. Брать, когда владелец ушёл и работа идёт ночь напролёт — готовый цикл одной работы, ветвление чередой, запись умолчания вместо вопроса, список к утру, разбор отказа стража. Не брать для обычного хода работы — это паттерны task-flow-start и task-flow-resume.
+---
+
+# Ночь без владельца
+
+Паттерн правила `autonomous-work`. Что при этом должно быть верно — закон
+`docs/constitution/autonomous-work.md`.
+
+## Когда брать
+
+- Владелец сказал, что уходит, и просил работать самостоятельно.
+- За заход берётся больше одной задачи подряд, и отдать их наружу нельзя.
+- Работа упёрлась в вопрос, а спросить некого.
+
+## Череда веток
+
+Первая работа ветвится от главной, каждая следующая — от предыдущей:
+
+```bash
+git checkout -b <КЛЮЧ>-<номер-1>-<slug> main           # первая за ночь
+git checkout -b <КЛЮЧ>-<номер-2>-<slug> <КЛЮЧ>-<номер-1>-<slug>
+git checkout -b <КЛЮЧ>-<номер-3>-<slug> <КЛЮЧ>-<номер-2>-<slug>
+```
+
+Порядок вливания — снизу вверх, и он называется в списке к утру номерами. Ветка, заведённая от
+главной посреди череды, столкнётся с соседкой в общих файлах — указателях, счётчиках, журналах —
+и разбирать это будет владелец.
+
+```bash
+git log --oneline --graph --decorate main..HEAD | head -20   # чем стоит череда сейчас
+git branch --list '<КЛЮЧ>-*' --format='%(refname:short) %(upstream:short)'
+```
+
+## Цикл одной работы
+
+```bash
+npm run task:move -- <номер> in-progress                 # взята
+git checkout -b <КЛЮЧ>-<номер>-<slug> <прошлая ветка>    # череда, а не веер
+cp -r docs/tasks/_template docs/tasks/<КЛЮЧ>-<номер>-<slug>
+# разбор просьбы с умолчаниями, замысел, состояние «этап-идёт»
+git add docs/tasks/<КЛЮЧ>-<номер>-<slug> && git commit    # папка едет в историю сразу
+# работа этапами: каждый кончается коммитом и прогоном признака готовности
+# папка разбирается в описание прошлого последним коммитом
+```
+
+Наружу за ночь не уходит ничего: ни `git push`, ни `gh pr create`, ни публикация, ни отметка
+груза. Ветка остаётся местной, и утром владелец сам решает, что из неё отдавать.
+
+## Умолчание вместо вопроса
+
+Пишется в разбор просьбы, в раздел решений, — там же, где записался бы ответ владельца:
+
+```markdown
+- **<что принято>** — <довод>. Спросить было некого: заход автономный. Цена ошибки:
+  <что придётся переделать, если владелец решит иначе>.
+```
+
+Цена ошибки — не вежливость, а признак: она отделяет умолчание, которое можно переиграть за
+десять минут, от того, ради которого работу лучше отложить целиком.
+
+## Отложенная задача
+
+Задача, которой нужно слово владельца, не берётся: состояние на борде остаётся прежним, а в
+список к утру идёт строка.
+
+```markdown
+- **RT-<номер> — <заголовок>.** Отложена: <какой вопрос и почему умолчания у него нет>.
+```
+
+## Список к утру
+
+Дописывается по ходу, после каждой закрытой работы, а не собирается в конце.
+
+```markdown
+| Работа | Ветка | Чем подтверждена | Чего ждёт |
+| ------ | ----- | ---------------- | --------- |
+| RT-… — <что сделано> | `<ветка>` (на `<предыдущей>`) | `<команда>` — <вывод> | заявки и слияния |
+```
+
+Порядок строк — порядок вливания. Ниже списка — отложенные задачи с их вопросами.
+
+## Отказ стража
+
+Отказ называет пропущенный шаг: шаг делается, вызов повторяется, работа идёт дальше. Ночь
+кончается работой, а не спором со стражем.
+
+- Отказ требует того, что делать нельзя (пуш, заявка), — работа доводится до места, где
+  требование исполнимо утром, и уходит в список к утру строкой «ждёт заявки».
+- Отказ повторяется на том же месте дважды — значит пропущенный шаг понят неверно: читается
+  правило, названное в отказе, а не переписывается формулировка.
+
+## Частые промахи
+
+- **Ветка заведена от главной по привычке.** Череда рвётся молча, и цена всплывает у владельца
+  на втором вливании.
+- **Умолчание принято и не записано.** Утром оно неотличимо от знания, и владелец узнаёт о нём,
+  только когда работа сделана не так.
+- **Задача взята и отложена наполовину.** На борде она в работе, в ветке — половина правки;
+  следующий заход читает её как начатую и не начинает заново.
+- **Список к утру собран по памяти в последнюю минуту.** К этому часу окно уже сжималось, и
+  половина ночи в него не попала.

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

@@ -19,7 +19,7 @@ description: Паттерн правила browser-verification. Брать, к
 ## Вывод подкрепляется числом
 
 `getComputedStyle`, `getBoundingClientRect`, контраст, совпадение центров, попадание во
-вьюпорт. «Выглядит нормально» результатом проверки не является.
+вьюпорт. «Выглядит нормально» результатом проверки не бывает.
 
 Замер отвечает только на тот вопрос, который задали. Совпадение перечисленных свойств ничего
 не говорит о правиле, которого в списке замера нет: строки попапа профиля сошлись с образцом
@@ -104,6 +104,20 @@ await (async (address, widths, row) => {
 Правка числа элементов в контейнере — это правка раскладки: она проверяется при 375, а не
 только кодами ответа.
 
+## Событие ввода подделкой значения не заменяется
+
+**Прокрутка, поставленная присвоением, события не даёт.** Значение прокрутки меняется, а подписчик
+не срабатывает ни на документе, ни на окне, ни на корневом узле: признак, который приложение
+считает по событию, остаётся прежним, и сделанная правка читается как несделанная — два захода
+подряд разбирали исправный слушатель.
+
+Отсюда две проверки, и ни одна не заменяет другую: механика проверяется настоящим колесом, а
+раскладка под признаком — признаком, поставленным руками. Класс ставится на хост, и меряется то,
+что от него зависит; порог при этом не участвует.
+
+Признак того, что случай именно этот: слушатель поставлен, значение прокрутки изменилось, счётчик
+событий нулевой. Разбирать после этого сам слушатель не нужно — он исправен.
+
 ## Ловушки инструмента `computer`
 
 - Координаты клика — координаты **скриншота**, а не CSS-пиксели: при вьюпорте 2560 скриншот
@@ -117,6 +131,32 @@ await (async (address, widths, row) => {
   настройками раскладки; спрашивается он у помощника, а не помнится: идентификатор локален для
   машины и в пакет не едет вовсе.
 
+## Долгий прогон запускается в странице, а не в вызове
+
+Вызов инструмента прерывается по своему пределу примерно на сорока пяти секундах, а начатый им
+обход продолжается — результата у него уже никто не спросит. Одна ширина из набора экранов идёт
+около полутора минут, то есть в вызов не помещается ни одна.
+
+Порядок такой: вызов кладёт обход в переменную страницы и заканчивается сразу, а следующие вызовы
+спрашивают у той же переменной, готово ли.
+
+```javascript
+globalThis.__probe = { done: false, rows: [] };
+(async () => {
+    for (const w of [375, 480, 481, 768, 769, 1080, 1081, 1380]) {
+        globalThis.__probe.rows.push(await measureWidth(w));
+    }
+    globalThis.__probe.done = true;
+})();
+
+'запущено';
+```
+
+Ответ инструмента обрезается примерно на полутора тысячах знаков без пометки: конец сводки
+выглядит не оборванным, а отсутствующим — вывод, собранный за один проход и напечатанный разом,
+читается как более короткий, чем он есть. Собранное поэтому остаётся в переменной целиком, а
+печатается срезами по индексу.
+
 ## Поведение роутера воспроизводится нажатиями
 
 Подстановка адреса, `history.pushState` с `popstate` и заход по прямой ссылке поднимают

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

@@ -17,15 +17,26 @@ description: Паттерн правила browser-verification. Брать, к
 - Порт отвечает не тем, чего ждали.
 - Нужен вход в админку.
 
+## Номера портов объявляет дерево, а не паттерн
+
+Команды ниже называют порты именами — `API_PORT`, `SITE_PORT`, `ADMIN_PORT`, `SSR_PORT`, порты
+стенда и порты прокси. Номеров у паттерна нет: раскладка стендов у каждого дерева своя, а дерево с
+одним приложением, обязанное назвать восемь чужих номеров, называет их выдуманными — и
+подстановки теряют смысл. Номера дерево объявляет своим профилем: в переменных окружения либо
+разделом надстройки при этом паттерне, где стоят его же готовые команды с именами целей раннера.
+
+Роль каждого имени — то, о чём говорит проза: порт приёмника, порт сайта, порт админки, порт
+сервера отрисовки. Дерево, у которого такого приложения нет, эти разделы не читает.
+
 ## Сначала — что отвечает на порту
 
 До первого запроса, а не после непонятного ответа:
 
 ```bash
-lsof -nP -iTCP:{{apiPort}} -sTCP:LISTEN
+lsof -nP -iTCP:$API_PORT -sTCP:LISTEN
 ```
 
-На {{apiPort}} регулярно висит собранный артефакт из прошлой сессии
+На порту приёмника регулярно висит собранный артефакт из прошлой сессии
 (`node -r dotenv/config dist/apps/api/main.js`): он отвечает 200 старым кодом, а процедуры,
 заведённой в ветке, у него нет вовсе. Таких процессов бывает несколько, и снимать надо все —
 по PID из `lsof`, каждый: `pkill` по шаблону `nx serve api` не попадает ни в один.
@@ -34,7 +45,7 @@ lsof -nP -iTCP:{{apiPort}} -sTCP:LISTEN
 
 ```bash
 npx nx build site
-PORT={{prodSitePort}} node dist/apps/site/server/server.mjs
+PORT=$SITE_STAND_PORT node dist/apps/site/server/server.mjs
 ```
 
 Это не дев-сервер: гард ловит `nx|ng serve`, пакетные раннеры и статические серверы, а запуск
@@ -72,17 +83,32 @@ Angular DevTools, нужна ещё и dev-конфигурация (`--configur
 человеку набрать пароль, открыть вкладку или нажать кнопку означает неверно выбранный путь, а
 не нехватку прав у исполнителя.
 
+**Спрашивают режим работы, а не ввод.** Ввод в поле пароля отбивает классификатор
+автоматического режима: он судит само действие и адресов не различает — стенд на местном порту
+выглядит для него боевым сайтом. Ход отсюда один: назвать владельцу отбитое действие, попросить
+обычный режим, заполнить форму парой засева самому и вернуться в автоматический режим. Просьба
+«войди сам» и «введи пароль» перекладывает на владельца работу агента и выглядит законной ровно
+потому, что перед ней стоит настоящее препятствие: отбитое поле, чужое расширение в браузере,
+отключившийся профиль. Препятствие остаётся препятствием агента.
+
+Пути, которыми препятствие снимается своими силами, — до всякой просьбы: подстановка значения
+инструментом формы по ссылке на элемент, выключение мешающего расширения в профиле браузера,
+подъём стенда на другом адресе. Второй драйвер полем пароля не оправдывается: он заполняет то же
+поле без классификатора, но обойдённый запрет снимается не с одного поля, а со всех сразу.
+Оставленный обычный режим снимает подтверждение и со всех последующих действий захода, поэтому
+возврат — часть входа, а не отдельная уборка.
+
 Стенд владельца запасным путём не бывает: он собирает главную ветку и о правке в рабочем дереве
 не говорит ничего.
 
 ## Стенд API
 
-Собранный артефакт поднимается на свободном порту, а не на {{apiPort}}: на {{apiPort}} отвечает API
+Собранный артефакт поднимается на свободном порту, а не на порту приёмника: там отвечает приёмник
 владельца, и окружение у него не то, которое проверяется.
 
 ```bash
 npx nx build api
-env -u JWT_SECRET NODE_ENV=production API_PORT={{prodApiPort}} DATABASE_URL=… node dist/apps/api/main.js
+env -u JWT_SECRET NODE_ENV=production API_PORT=$API_STAND_PORT DATABASE_URL=… node dist/apps/api/main.js
 ```
 
 Переменные окружения задаются в самой команде, по одной на проверяемый случай. Отказ на
@@ -92,7 +118,7 @@ env -u JWT_SECRET NODE_ENV=production API_PORT={{prodApiPort}} DATABASE_URL=…
 Процедура зовётся полным именем, как её объявляет контракт:
 
 ```bash
-curl -sS -X POST http://localhost:{{prodApiPort}}/<область>.v1.AuthService/GetMe \
+curl -sS -X POST http://localhost:$API_STAND_PORT/<область>.v1.AuthService/GetMe \
     -H 'content-type: application/json' -H "authorization: Bearer $TOKEN" -d '{}'
 ```
 
@@ -108,7 +134,7 @@ curl -sS -X POST http://localhost:{{prodApiPort}}/<область>.v1.AuthServic
 ```bash
 docker run -d --name <префикс>-stand-nginx \
   --add-host api:host-gateway --add-host ssr:host-gateway \
-  -p {{dockerSitePort}}:80 -p {{dockerAdminPort}}:8081 \
+  -p $PROXY_SITE_PORT:80 -p $PROXY_ADMIN_PORT:8081 \
   -v "$PWD/deploy/nginx/main.conf:/etc/nginx/nginx.conf:ro" \
   -v "$PWD/deploy:/etc/nginx/conf.d:ro" \
   -v "$PWD/dist/apps/admin/browser:/usr/share/nginx/html/admin:ro" \
@@ -126,9 +152,24 @@ docker run -d --name <префикс>-stand-nginx \
   тем же, чем и на свой. За настоящим прокси запросы идут со своим заголовком ровно потому, что
   прокси стоит перед дев-сервером, — оттуда и `-H "Host: localhost"`.
 - Переменные окружения стенда обязаны смотреть на процессы стенда. `CACHE_REFRESH_URL`,
-  направленный на {{sitePort}}, сбрасывает кэш мимо того процесса, который держит справочник
+  направленный на порт сайта, сбрасывает кэш мимо того процесса, который держит справочник
   перенаправлений в памяти, — исправный механизм при этом выглядит сломанным.
 
+## Стенд живёт ровно столько, сколько проверка
+
+Стенд поднят под один вывод и после него не нужен. Брошенный не мешает ничему и не подаёт сигнала:
+имя у него своё, порт свободный, места он почти не занимает — увидеть его можно только вызовом
+списка, а звать его незачем. Разбирать накопленное поэтому приходится человеку, и отличить
+брошенный от живого стенда соседнего дерева он по имени не может.
+
+Снос идёт тем же ходом, которым сделан вывод:
+
+```bash
+docker rm -f <имя стенда>
+```
+
+Имя даётся по номеру задачи — так видно, чей стенд остался, если ход всё-таки оборвался.
+
 ## Дерево для сравнения
 
 Сказать «это сломала правка» можно, только если видно, что до правки было иначе. Проверяют это
@@ -142,8 +183,8 @@ pnpm install --frozen-lockfile         # из ../<префикс>-base: node_mod
 - Для сравнения берут не главную ветку, а последний коммит, на котором дерево собирается:
   главная бывает сломана, и тогда «до» и «после» различаются не из-за правки. Собирается ли
   коммит — проверяют сборкой, а не тем, что он в главной ветке.
-- Стенд второго дерева поднимают на своих портах: {{sitePort}}, {{adminPort}} и {{apiPort}} заняты владельцем, а {{ssrPort}}
-  занимать нельзя — стенд разработчика ходит по имени `ssr:{{ssrPort}}`.
+- Стенд второго дерева поднимают на своих портах: порты сайта, админки и приёмника заняты владельцем, а порт отрисовки
+  занимать нельзя — стенд разработчика ходит по имени `ssr:<порт отрисовки>`.
 - Оба стенда держат поднятыми одновременно — ровно до конца сравнения: если сравнивать по памяти
   между двумя запусками, заметишь только то, что успел запомнить. Со сравнением стенд второго
   дерева гасится тем же ходом, а не оставляется до конца захода: оставленные стенды копятся
@@ -157,7 +198,7 @@ pnpm install --frozen-lockfile         # из ../<префикс>-base: node_mod
 приписать своей сборке, ни снять с неё подозрение.
 
 ```bash
-for u in http://localhost:{{apiPort}}/health http://localhost:{{sitePort}}/ http://localhost:{{adminPort}}/; do
+for u in http://localhost:$API_PORT/health http://localhost:$SITE_PORT/ http://localhost:$ADMIN_PORT/; do
     printf '%s %s\n' "$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "$u")" "$u"
 done
 ```
@@ -169,10 +210,10 @@ done
 
 - **Одиночная сборка проекта серверы переживают, и отказываться от неё незачем.** Замерено
   ответом до и после: все порты остались за своими процессами. Осторожность здесь стоит дороже
-  проверки — целая команда паттерна `seo-verify` осталась незапущенной ровно потому, что сборку
-  сочли опасной, не замерив. Сборка из кэша замером не является: она не собирает вовсе, и видно
+  проверки — целый набор проверок разметки остался незапущенным ровно потому, что сборку
+  сочли опасной, не замерив. Сборка из кэша замером не бывает: она не собирает вовсе, и видно
   это по её длительности.
-- Свой дев-сервер не поднимать: сайт на {{sitePort}}, админка на {{adminPort}}, API на {{apiPort}} уже подняты
+- Свой дев-сервер не поднимать: сайт, админка и приёмник уже подняты
   владельцем, и второй экземпляр отбивается гардом.
 - **Отбитый статический сервер читается как запрет проверки, а он указание на верный ход.**
   Отдавать собранное им нельзя не из осторожности: приложение ходит на свой origin, а глубокая
@@ -184,8 +225,8 @@ done
   поднятый дев-сервер годится, чтобы понять, что происходит на незнакомом экране, и не годится
   подтверждением: подтверждение — замер на стенде из прод-сборки.
 - **Общая сборка глушит все три дев-сервера владельца, а не только API.** После
-  `nx run-many -t build` ложатся и сайт на {{sitePort}}, и админка на {{adminPort}}. Собирать надо то, что
+  `nx run-many -t build` ложатся и сайт, и админка. Собирать надо то, что
   проверяешь (`npx nx build site`), а не всё дерево. Если серверы легли, поднять их обратно
   агент не может — мешает гард, поэтому владельцу говорят об этом сразу, а не в конце сессии.
-- Порт {{ssrPort}} занимать осторожно: стенд разработчика на {{sitePort}} ходит по тому же имени `ssr:{{ssrPort}}`
+- Порт отрисовки занимать осторожно: стенд разработчика ходит по тому же имени `ssr:<порт отрисовки>`
   через `host-gateway`, и пока на нём висит чужой процесс, стенд отдаёт чужую сборку.

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

@@ -0,0 +1,75 @@
+---
+name: doc-style-human
+kind: pattern
+rule: doc-style
+description: Паттерн правила doc-style. Брать при написании задачи в очереди работ, описания заявки и ответа владельцу в чате. Образцы «так» и «не так» на каждый из трёх текстов и разбор слов, которые в них заменяются. Форму ответа о состоянии работы называет правило status-report.
+---
+
+# Задача, описание заявки и ответ владельцу
+
+Паттерн правила `doc-style`. Три текста читает человек со стороны: он помнит продукт и не
+читал ни одного правила слоя. Здесь — как они пишутся; что при этом должно быть верно, говорит
+раздел «Тексты для человека» самого правила.
+
+## Когда брать
+
+- Заводится задача в очереди работ.
+- Пишется описание заявки на слияние.
+- Пишется ответ владельцу в чате — кроме ответа о состоянии работы: его форму называет правило
+  `status-report`.
+
+## Слова, которые заменяются
+
+Левая колонка — слова слоя правил. Они верны внутри слоя и пусты для того, кто в него не
+заглядывает.
+
+| Слово слоя         | Чем сказать владельцу                                      |
+| ------------------ | ---------------------------------------------------------- |
+| заявка на слияние  | правка, которая ждёт вашего слова                          |
+| прогон, набор      | проверки; «проверки прошли», «проверки красные»            |
+| гард, гейт         | что именно не пустило и почему                             |
+| договорённость     | о чём договорились по этому экрану                         |
+| объём правки       | что меняется на экране и где                               |
+| раскладка ресурсов | обновление правил на машине                                |
+
+## Задача
+
+Заголовок называет предмет, тело — что человек не может сделать. Красная проверка стоит в теле
+последней строкой: она говорит, где смотреть, и не говорит, зачем чинить.
+
+```text
+✗ Сквозная спека берёт пункт заглушкой, а прогон на вершине не доходит до выкатки
+✓ Раздел «Отчёты» не открывается у пользователя, и из-за этого не идёт выкатка.
+  Красная проверка — сквозной набор, шаг «отчёты».
+```
+
+## Описание заявки
+
+Первый абзац — что меняется для человека. Дальше — чем это подтверждено. Имена файлов уместны
+в конце, а не вместо первого абзаца.
+
+```text
+✗ Ярус личности вызова получил второй признак, набор гейта зелёный
+✓ Заявки от машинной записи больше не открываются от имени владельца: теперь перед открытием
+  спрашивается, кто приходит по токену. Проверки прошли, 26 сценариев.
+```
+
+## Ответ в чате
+
+Отвечает на заданный вопрос первым предложением. Утверждение о дереве идёт вместе с командой и
+её выводом — этого требует правило `status-report`, и в чате оно верно так же.
+
+```text
+✗ Работа отдана, красное въехало в главную, откат прикрыт гардом
+✓ Правку я отправил, она ждёт вашего слова. В главной ветке сейчас красный шаг «сборка витрины»
+  — упал не на этой правке, вывод: 76 из 76 сценариев не поднялись, витрина лежит.
+```
+
+## Ловушки
+
+- **Короче не значит понятнее.** Текст словами слоя выходит на треть короче и бесполезен тому,
+  кто решает, срочная это работа или нет.
+- **«Не X, а Y» выглядит объяснением и ничего не объясняет.** Владелец узнаёт, чего не было, и
+  не узнаёт, что есть.
+- **Слово «готово» без числа читается как проверенный факт.** Число — номер прогона, сколько
+  сценариев из скольких, время проверки.

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

@@ -104,6 +104,22 @@ description: Паттерн правила doc-style. Брать при напи
 его вместе со смыслом. Считается это грепом по тексту, и число само по себе отказом не бывает:
 судит его тот, кто правит следующим.
 
+## Новое слово в словаре
+
+Слово, значащее в дереве что-то определённое, живёт в словаре. Порядок — четыре шага, и первый
+из них не пропускается: словарь читается до того, как текст написан, а не сверяется после.
+
+1. **Поиск по собранному словарю целиком**, включая раздел отвергнутых слов. Слово, от которого
+   дерево отказалось, стоит там же — и вводить его заново значит отменять чужое решение молча.
+2. **Выбор своего раздела.** Раздел надстройки замещает одноимённый раздел набора целиком:
+   название берётся такое, какого в наборе нет.
+3. **Строка парой — слово и что это.** Без второй половины слово не введено: оно названо.
+4. **Раскладка тем же изменением**, и сверка при этом зелёная. Слово, введённое в надстройку и не
+   разложенное, у читателя ещё не появилось.
+
+Слово, от которого дерево отказывается, заводится там же и с заменой в той же строке: отказ без
+замены исполнить нечем — пишущий видит запрет и не видит, чем его закрыть.
+
 ## Факт проверяется, а не вспоминается
 
 Перед тем как написать, что код делает X, — открыть код и посмотреть. Пересказ по памяти

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

@@ -25,6 +25,13 @@ description: Паттерн правила git-workflow. Брать на зав
 
 Все четыре делает одна команда дерева, а не рука: делить их значит забывать последний.
 
+**Команду, которой нет, паттерн не заменяет вызовами клиента.** Дерево, взявшее пакет впервые,
+получает файлы проверок, но не записи о них в своём манифесте: раскладка правит ресурсы, а
+манифест потребителя ей не принадлежит. Ходов отсюда два: завести команду тем же ходом либо
+повторить все её шаги поимённо по перечню выше. Обход вызовами клиента выглядит исполнением до
+последнего шага перечня: он забывается первым, потому что предыдущие уже дали видимый
+результат.
+
 ```bash
 npm run task:new -- --title 'Письма владельцу не уходят молча' \
     --type Bug --area '<проект>\<команда>' --slug mail-owner-silence < описание.md
@@ -151,6 +158,11 @@ Docs-skip: правка только в тестах хука, зеркала у
 
 ## Частые промахи
 
+- **Сверка сразу после добавления отвечает «нет», когда карточка уже стоит.** Очередь работ отдаёт
+  новый элемент не в ту же секунду, в какую его завели, а последний шаг читает её следующим
+  вызовом. Ответ на это — перечитать очередь целиком, а не завести карточку второй раз: две записи
+  об одной задаче снимает только администратор. Сама команда заведения при этом требует правки:
+  состояние читается сразу за мутацией, без повтора, и ложный отказ здесь дороже задержки.
 - Область и итерация не заданы: элемент заведён, но на доску команды не попал.
 - Состояние взято не из процесса проекта: перевод отвечает отказом на каждой задаче, и это
   читается как сломанная команда, а не как неверное имя состояния.

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

@@ -26,6 +26,14 @@ description: Паттерн правила git-workflow. Брать на зав
 
 Все четыре шага делает одна команда дерева, а не рука: делить их значит забывать третий.
 
+**Команду, которой нет, паттерн не заменяет вызовами клиента.** Дерево, взявшее пакет впервые,
+получает файлы проверок, но не записи о них в своём манифесте: раскладка правит ресурсы, а
+манифест потребителя ей не принадлежит. Ходов отсюда два: завести команду тем же ходом либо
+повторить все её шаги поимённо по перечню выше. Обход вызовами клиента выглядит исполнением до
+последнего шага перечня: он забывается первым, потому что предыдущие уже дали видимый
+результат. Так карточка простояла вне
+колонок всю работу — два коммита и два закрытых этапа.
+
 **Локальные ветки этой задачи читаются до заведения новой.** Борда не видит ветки, и задача, по
 которой работа лежит доделанной в локальной ветке, выглядит открытой у всех: колонку двигают
 рукой, заявки нет, а ветка видна только на той машине, где её завели. Под один номер так
@@ -87,7 +95,7 @@ gh project item-add <номер борды> --owner <владелец> --url <а
 который его показывает. Не нашлось ни того ни другого — задача не заводится, а строка документа
 правится тем ходом, которым её прочитали.
 
-Название тикета говорит, что не так, а не что сделать: PR потом переводит его в сделанное.
+Название задачи говорит, что не так, а не что сделать: PR потом переводит его в сделанное.
 Номер в заголовок руками не пишется — он известен только после создания, и команда дописывает
 его сама.
 
@@ -97,7 +105,7 @@ gh project item-add <номер борды> --owner <владелец> --url <а
 npm run check:board
 ```
 
-Она смотрит только открытое: тикеты на борде, номер и исполнителя у каждой открытой задачи,
+Она смотрит только открытое: задачи на борде, номер и исполнителя у каждой открытой задачи,
 а у каждого открытого PR — номер в заголовке, строку `Closes`, открытую задачу за ним и то,
 что второго PR с тем же номером нет. Имя ветки не судит: у открытого PR его не переименовать.
 
@@ -209,6 +217,11 @@ Docs-skip: правка только в тестах хука, зеркала у
 
 ## Частые промахи
 
+- **Сверка сразу после добавления отвечает «нет», когда карточка уже стоит.** Очередь работ отдаёт
+  новый элемент не в ту же секунду, в какую его завели, а последний шаг читает её следующим
+  вызовом. Ответ на это — перечитать очередь целиком, а не завести карточку второй раз: две записи
+  об одной задаче снимает только администратор. Сама команда заведения при этом требует правки:
+  состояние читается сразу за мутацией, без повтора, и ложный отказ здесь дороже задержки.
 - `gh` в оболочке пользователя подменён — звать `/opt/homebrew/bin/gh` напрямую.
 - Каталог добавлен целиком при чужом незакоммиченном рядом: чужая папка задачи уехала в главную ветку и стала отслеживаемой.
 - `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
@@ -223,7 +236,7 @@ Docs-skip: правка только в тестах хука, зеркала у
 - `gh project` с `--owner` отвечает `unknown owner type`: владелец борды — другая учётная
   запись, и правка идёт только через GraphQL.
 - Заведённую задачу на борду сама она не забирает: репозиторий с ней не связан, и добавление
-  идёт отдельным вызовом. Два тикета так и остались вне очереди работ — поэтому все четыре
+  идёт отдельным вызовом. Две задачи так и остались вне очереди работ — поэтому все четыре
   шага и делает `npm run task:new`, а не рука.
 - Исполнитель у задачи не проставляется сам ни при заведении через веб, ни при добавлении на
   борду: из девяноста девяти открытых задач он стоял у двух.

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

@@ -25,6 +25,13 @@ description: Паттерн правила git-workflow. Брать на зав
 
 Все четыре делает одна команда дерева, а не рука: делить их значит забывать последний.
 
+**Команду, которой нет, паттерн не заменяет вызовами клиента.** Дерево, взявшее пакет впервые,
+получает файлы проверок, но не записи о них в своём манифесте: раскладка правит ресурсы, а
+манифест потребителя ей не принадлежит. Ходов отсюда два: завести команду тем же ходом либо
+повторить все её шаги поимённо по перечню выше. Обход вызовами клиента выглядит исполнением до
+последнего шага перечня: он забывается первым, потому что предыдущие уже дали видимый
+результат.
+
 ```bash
 npm run task:new -- --title 'Письма владельцу не уходят молча' \
     --label bug --label area:api --slug mail-owner-silence < описание.md
@@ -156,6 +163,11 @@ Docs-skip: правка только в тестах хука, зеркала у
 
 ## Частые промахи
 
+- **Сверка сразу после добавления отвечает «нет», когда карточка уже стоит.** Очередь работ отдаёт
+  новый элемент не в ту же секунду, в какую его завели, а последний шаг читает её следующим
+  вызовом. Ответ на это — перечитать очередь целиком, а не завести карточку второй раз: две записи
+  об одной задаче снимает только администратор. Сама команда заведения при этом требует правки:
+  состояние читается сразу за мутацией, без повтора, и ложный отказ здесь дороже задержки.
 - Метка списка не поставлена при заведении: задача есть, а на доске её нет. Доска показывает
   только то, чью метку знает.
 - Перевод по списку не снял прежнюю метку: задача стоит в двух списках сразу.

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

@@ -40,6 +40,7 @@ git diff --name-only --diff-filter=U     # что встало конфликт
 | Что встало конфликтом            | Как разрешается                                                                    |
 | -------------------------------- | ---------------------------------------------------------------------------------- |
 | код                              | ловушка правила `git-workflow` про сторону-удаление; после — `npm run check:dupes` |
+| сборка из описания               | собирается заново из описания после того, как описание разрешено: строки в такой файл пишет генератор, и соединённые руками стороны дают файл, которого он не выдаст |
 | спек в `docs/specs/`             | сохранением обеих сторон, если обе дописывали; снятый одной стороной раздел остаётся снятым — правило `spec-driven`; после — `npm run check:specs` |
 | компаньон правила рядом со скилом | сохранением обеих сторон — те же две дописи в одну таблицу; после — `npm run check:specs` |
 | список работ (`docs/BACKLOG.md`) | признаком отбора — паттерн `doc-style-sweep`                                       |
@@ -92,6 +93,13 @@ git checkout --theirs docs/BACKLOG.md && git add docs/BACKLOG.md
 
 ## Проверки после разрешения
 
+**Конфликт в разложенном файле, который исполняется, разрешается тем же вызовом, каким
+обнаружен.** Маркеры в теле гарда — синтаксическая ошибка, а не расхождение текста: ветка падает,
+диспетчер отдаёт её код отказом, и следующего вызова оболочки уже не будет — вместе с ней
+отбиваются и остальные двери, названные в объявлении этого гарда. Исполняемый файл узнаётся
+строкой `# rt-hook:` в шапке; отложенное «поправлю потом» здесь означает заход, который нечем
+продолжить.
+
 Конфликт в текстах кода не задевает, и зелёная сборка про него ничего не говорит:
 
 ```bash