@rt-tools/agent-kit 0.8.1 → 0.8.3

package/assets/rules/browser-verification.md

@@ -26,11 +26,45 @@ description: Правило под «Закон о проверяемости».
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход проверки через браузер: что выясняется до первого запроса, где развилка между поднятым и
+не поднятым приложением и чем подтверждается вывод.
+
+```mermaid
+flowchart TD
+    A[Нужна проверка в браузере] --> B{Порт занят}
+    B -->|Да| C[Выясняется, что именно отвечает]
+    B -->|Нет| D{Кто поднимает стенд}
+    C --> E{Отвечает то самое приложение}
+    E -->|Да| F[Второй экземпляр не поднимается]
+    E -->|Нет| T[Занявшее порт останавливается по идентификатору процесса, а не по имени команды]
+    T --> D
+    D -->|Владелец| U[Ему говорят сразу, а не в конце захода: агента отбивает гард]
+    D -->|Агент| V[Стенд поднимается]
+    U --> G[Драйвер водит браузер на закреплённом профиле]
+    V --> G
+    F --> G
+    G --> W{Экран публичный и это первый заход}
+    W -->|Да| X[Заход метится признаком служебного посещения: иначе он попадёт в счёт гостей]
+    W -->|Нет| H{Что проверяется}
+    X --> H
+    H -->|Путь запроса и отдача страницы| I[Проверка идёт за настоящим прокси]
+    H -->|Вёрстка| J[Замер вычисленных значений, а не взгляд]
+    I --> K{Расхождение объясняется кэшем}
+    J --> K
+    K -->|Да| L[Кэш чистится и замер повторяется: объяснение не подтверждение]
+    K -->|Нет| M[Вывод называет число и способ его получить]
+    L --> M
+```
+
 ## Как закон применяется здесь
 
 - **Второй экземпляр уже поднятого приложения не поднимается.** До первого запроса выясняется,
   кто отвечает на порту: поднятый заново экземпляр отвечает своей сборкой, а не той, которую
-  проверяют. Кто поднимает стенд — владелец или агент, — сказано в именах дерева.
+  проверяют. Кто поднимает стенд — владелец или агент, — сказано в именах дерева. Занятый порт,
+  обнаруженный поздно, означает, что стенд уже есть: запущенное поверх него останавливается по
+  идентификатору процесса, а не по имени команды — у обоих экземпляров оно одно.
 - **Браузер водится одним драйвером на закреплённом профиле.** Остальные двери — второй
   драйвер, `open`, `osascript`, запуск бинарника — закреплённый профиль не спрашивают вовсе.
 - **Выбор браузера протухает и требует повторного вызова.** Выбор, сделанный в начале
@@ -66,6 +100,13 @@ description: Правило под «Закон о проверяемости».
   отвечает 200 старым кодом, а заведённого в ветке обработчика у него нет вовсе, и 404 читается
   как дефект регистрации. Таких процессов бывает несколько; снятие по шаблону команды не
   попадает ни в один — убивать по PID из `lsof`, каждый.
+- **Шаблон имени команды не годится ни чтобы попасть, ни чтобы не задеть.** Два экземпляра
+  одного стенда — уже поднятый и только что запущенный — по тексту команды неотличимы: она у них
+  одна и та же. Снятие по шаблону уносит оба, и разобрать это потом нечем: снятым оказывается
+  ровно тот стенд, ради которого всё затевалось. Своё и чужое различает только идентификатор
+  процесса, снятый разбором порта; им и останавливают, поштучно. Обратный промах тот же по
+  природе — оболочка запускает процесс под именем, которого в шаблоне нет, и снятие не попадает
+  ни во что.
 - Инкрементальная сборка протухает поштучно: разметка бывает уже новая, а клиентский чанк — от
   компиляции до правки. Признак дев-сборки — имена бандла без хеша (`main.js`). Расхождение
   между `curl` и страницей после гидратации — повод пересобрать, а не искать дефект в коде.

package/assets/rules/component-structure.md

@@ -27,6 +27,27 @@ description: Правило под «Закон о фронтовом прило
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход правки компонента: где решается разметка, где — привязка, и что ставится на каждый
+интерактивный элемент.
+
+```mermaid
+flowchart TD
+    A[Правится компонент] --> B[Селектор элементный, класс блока на хосте]
+    B --> C{В шаблоне нужен вычисленный вид}
+    C -->|Да| D[Значение считается в классе, шаблон методов не зовёт]
+    C -->|Нет| E[Разметка пишется как есть]
+    D --> F{Есть интерактивный элемент}
+    E --> F
+    F -->|Да| G[Ставится якорь для спек, а доступность — отдельными атрибутами]
+    F -->|Нет| H[Готово]
+    G --> I{Один компонент в обеих ветках условия}
+    I -->|Да| J[Это условная привязка: ветки сводятся в одну]
+    I -->|Нет| H
+    J --> H
+```
+
 ## Как закон применяется здесь
 
 - **Шаблон не зовёт методов.** Правило линтера банит `{{ getTotal() }}` и `@if

package/assets/rules/dependencies.md

@@ -27,6 +27,28 @@ description: Правило под «Закон о поставке». Брат
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход подъёма версии: где решается сама версия, где — граница переформатирования, и чем работа
+кончается.
+
+```mermaid
+flowchart TD
+    A[Нужна новая версия пакета] --> B{Верхняя граница чем задана}
+    B -->|Есть peer-диапазоны у зависимых| C[Граница берётся из них, а не из последнего номера в реестре]
+    B -->|Нет| D[Берётся последняя выпущенная]
+    C --> E{Версия выпущена недавно}
+    D --> E
+    E -->|Да, и она нужна прямо сейчас| F[Выписывается отдельно, с названной причиной]
+    E -->|Да, но не срочно| G[Выдерживается: свежая версия отзывается чаще старой]
+    E -->|Нет| H[Записывается точным номером, без диапазона]
+    F --> H
+    H --> I{Обновился форматтер или линтер}
+    I -->|Да| J[Переформатируется только то, что линтер и проверяет; новые правила разбираются поимённо]
+    I -->|Нет| K[Снимок дерева пересобирается, набор гоняется целиком]
+    J --> K
+```
+
 ## Как закон применяется здесь
 
 - **Версия пакета записана точным номером.** Из диапазона сегодня и через неделю поставится

package/assets/rules/doc-style.md

@@ -27,6 +27,30 @@ description: Правило под «Закон о документации пр
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход правки текста: что проверяется до записи, где развилка между новым словом и уже занятым, и
+что делается со снятым именем.
+
+```mermaid
+flowchart TD
+    A[Пишется текст проекта] --> B{Нужно слово для нового понятия}
+    B -->|Да| C{Оно есть в словаре}
+    C -->|Да| D[Берётся оттуда в том же значении]
+    C -->|Нет| E[Заводится в словаре той же правкой либо заменяется простым]
+    B -->|Нет| F{В тексте называется путь или имя файла}
+    D --> F
+    E --> F
+    F -->|Да| G[Путь проверяется командой: названный, но несуществующий читается как указание]
+    F -->|Нет| H{В тексте стоит число или утверждение о проверке}
+    G --> H
+    H -->|Число| I[Пересчитывается командой в том же изменении либо не пишется вовсе]
+    H -->|Проверка| J[Запускается, а не пересказывается]
+    H -->|Ни то ни другое| K[Документ едет тем же коммитом, что и правка, которую описывает]
+    I --> K
+    J --> K
+```
+
 ## Как закон применяется здесь
 
 - **Путь, названный в документе, существует.** Ссылка на переехавший файл читается как
@@ -115,7 +139,7 @@ description: Правило под «Закон о документации пр
   паттерн `doc-style-sweep`.
 - **Словарь действует и на разговор с владельцем, не только на файлы.** Он приходит в контекст
   на запуске сессии, поэтому «не читал» основанием не бывает. Слово из левой колонки «Так не
-  пишем» всплывало именно в ответах: в дереве его уже вычистили, а в отчёте о сделанном оно
+  пишем» всплывало именно в ответах: в дереве его уже вычистили, а в PR о сделанном оно
   оставалось, и владелец читал ровно то слово, от которого отказались.
 - **Термин берётся из `docs/GLOSSARY.md`, а не придумывается на месте.** Слова, которого там
   нет, у читателя нет тоже: «журнал приложения» простоял в спеке почты, пока владелец не
@@ -131,19 +155,27 @@ description: Правило под «Закон о документации пр
 - **Снятое имя вычищается одним грепом по всему дереву:** правила, их зеркала в скилах,
   документы и комментарии. Описание того, чего в коде уже нет, читается как действующее
   указание.
+- **У снятого слова второе значение возвращается после сплошной замены, а не обходится до
+  неё.** Слово снимают ровно потому, что оно стояло над двумя вещами, и второе значение при
+  этом остаётся законным. Отобрать его заранее нечем: какое из двух значений в строке, видно
+  только по соседнему тексту, а строк бывают сотни. Порядок обратный — сплошная замена, затем
+  сплошной просмотр самой правки, и найденное второе значение возвращается поимённо. Из 353
+  замен так вернулись шесть, и две первые были поломкой: сверка печатала новое имя дважды
+  подряд, а комментарий обещал «поломку вместо PR о том, что долгов нет». Просматривается
+  правка, а не дерево после неё: в дереве обе стороны выглядят одинаково верными.
 - **Поиск по дереву не покрывает того, что уже уехало наружу.** Заголовок задачи и её тело,
-  заголовок отчёта и его тело, заголовки коммитов лежат вне файлов, и проверки текстов их не
+  заголовок PR и его тело, заголовки коммитов лежат вне файлов, и проверки текстов их не
   читают вовсе. Вычистив слово в дереве, обходят те же места в очереди работ и в истории:
 
     ```bash
-    <клиент хостинга> api "<путь к отчёту>" --jq '.title, .body' | grep -i '<слово>'
+    <клиент хостинга> api "<путь к PR>" --jq '.title, .body' | grep -i '<слово>'
     <клиент хостинга> api "<путь к задаче>" --jq '.title, .body' | grep -i '<слово>'
     git log --format='%s%n%b' <база>..HEAD | grep -i '<слово>'
     ```
 
-    Заголовок отчёта правится вызовом хостинга, заголовок коммита — только переписыванием ветки,
+    Заголовок PR правится вызовом хостинга, заголовок коммита — только переписыванием ветки,
     поэтому его проверяют до пуша. Выдуманное слово было вычищено из трёх файлов и объявлено
-    снятым, а в заголовке отчёта и в заголовке коммита осталось — владелец прочитал именно его.
+    снятым, а в заголовке PR и в заголовке коммита осталось — владелец прочитал именно его.
 
 - **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет
   внутри одной ветки: «шестнадцать пар» стало неправдой через два коммита после того, как

package/assets/rules/{entity-conventions.md → entity-conventions.needs-admin.md}

@@ -28,6 +28,27 @@ description: Правило под «Закон о правке сущности
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход правки записи из панели: чем панель открывается, что происходит с мутацией и чем кончается
+уход с панели.
+
+```mermaid
+flowchart TD
+    A[Нужна панель создания или правки] --> B[Открывается маршрутом во вспомогательном аутлете]
+    B --> C[Запись читается по признаку из адреса полной моделью, а не берётся из списка]
+    C --> D[Панель наследует общую основу и отдаёт ей поток мутации]
+    D --> E{Мутация чем кончилась}
+    E -->|Значение| F[Список перечитывается, и только после этого работа считается сделанной]
+    E -->|Ошибка потока| G[Панель показывает отказ и остаётся открытой]
+    E -->|Пусто| H[Так не бывает: пустой поток гасит панель навсегда]
+    F --> I{Уход с панели}
+    G --> I
+    I -->|Есть несохранённые правки| J[Гард спрашивает — на всех путях закрытия сразу]
+    I -->|Нет| K[Уход идёт общим переходом к связанной записи, а не своим маршрутом]
+    J --> K
+```
+
 ## Как закон применяется здесь
 
 - **Асайд открывается маршрутом в аутлете `ro`, а не вызовом сервиса.** Программного открытия

package/assets/rules/entity-models.md

@@ -28,6 +28,27 @@ description: Правило под «Закон о моделях сущност
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход заведения модели: две стороны сущности, кто из них пишется руками и где стоит перевод между
+ними.
+
+```mermaid
+flowchart TD
+    A[Заводится модель записи] --> B[Обе стороны живут в одном неймспейсе имени сущности]
+    B --> C{Сторона контракта}
+    C -->|Объявляется псевдонимом сгенерированного типа| D[Руками не пишется: своя копия разойдётся молча]
+    D --> E[Между сторонами встаёт маппер-наследник общей основы]
+    E --> F{Значение пришло не в том виде}
+    F -->|Да| G[Приведение идёт способом маппера, а не подстановкой по умолчанию]
+    F -->|Нет| H[Экраны читают только сторону состояния]
+    G --> H
+    H --> I{Нужны страница, порядок или отбор}
+    I -->|Да| J[Типы берутся из общего набора: второго такого не заводится]
+    I -->|Нет| K[Пустое выражается пустой строкой или нулём, а не отсутствием поля]
+    J --> K
+```
+
 ## Как закон применяется здесь
 
 - **У сущности две стороны, и обе лежат в неймспейсе `I<Сущность>`.** `Api` повторяет

package/assets/rules/git-workflow.azure.md

@@ -21,7 +21,7 @@ description: Правило под «Закон о поставке» для д
 | задача                           | рабочий элемент (work item) рода `Task` или `Bug`, заголовок `[<номер>] <Что не так>`, исполнитель — учётная запись машинной работы; PR прикрепляется к нему при создании флагом `--work-items`, а коммит — строкой `AB#<номер>`       |
 | очередь работ                    | Azure Boards проекта. Рабочий элемент попадает на доску тем, что заведён: доска показывает элементы своей области и итерации                                                                                                           |
 | состояние задачи в очереди работ | поле `State` рабочего элемента: `New` у заведённого, `Active` у взятого в работу, `Resolved` у ждущего разбора. Набор состояний зависит от процесса проекта и назван в `implementation.md`; закрытая задача уходит из очереди слиянием |
-| отчёт о задаче                   | заголовок PR `[<номер>] <Что сделано>` — тот же номер, что у рабочего элемента, и его название, переведённое в сделанное; тип и область коммита сюда не идут                                                                           |
+| PR о задаче                      | заголовок PR `[<номер>] <Что сделано>` — тот же номер, что у рабочего элемента, и его название, переведённое в сделанное; тип и область коммита сюда не идут                                                                           |
 | обсуждение правки                | разбор PR: ревьювер — владелец репозитория, исполнитель — учётная запись машинной работы, метки — те же, что у рабочего элемента                                                                                                       |
 | попадание правки в главную ветку | слияние PR; оно же запускает выкатку — `azure-pipelines.yml`                                                                                                                                                                           |
 | образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                                                               |
@@ -35,6 +35,30 @@ description: Правило под «Закон о поставке» для д
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход работы от задачи до слияния: где стоит гард, что двигает колонку очереди работ и чем
+работа кончается.
+
+```mermaid
+flowchart TD
+    A[Работа начинается] --> B[Задача заводится командой и встаёт в очередь работ]
+    B --> C[Ветка называется номером задачи; колонка двигается тем же движением]
+    C --> D{Правка готова}
+    D -->|Нет| C
+    D -->|Да| E[Главная ветка влита, набор гейта прогнан целиком]
+    E --> F{Ветка несёт номер задачи}
+    F -->|Нет| G[Гард поставки отбивает открытие: за правкой ничего не стоит в очереди]
+    F -->|Да| H[PR открывается; не готовое к слиянию идёт черновиком]
+    H --> I[Колонка задачи переходит в разбор, исполнитель берёт следующую задачу]
+    I --> J{Прогон и разбор кончились}
+    J -->|Прогон красный| K[Чинится в той же ветке]
+    K --> J
+    J -->|Зелено| L[Папка задачи разбирается последним коммитом, черновик снимается]
+    L --> M[Слияние нажимает человек: исполнитель просит и называет номер]
+    G --> B
+```
+
 ## Как закон применяется здесь
 
 - **Коммит в главную ветку отбивается гардом.** Гард ищет вызов коммита в любом месте команды
@@ -48,6 +72,25 @@ description: Правило под «Закон о поставке» для д
   открытие, пока вершина главной ветки не стала предком текущей, и называет расхождение числом
   коммитов. PR с разошедшейся ветки показывает ревьюверу свою правку вперемешку с чужой, а всё,
   что автор проверил до публикации, он проверил от основания, которого в главной ветке уже нет.
+- **Правка кода отдаётся человеку открытым PR, а не запушенной веткой.** Ветка в списке ветвей
+  ему не показывается, в его дела не приходит и обсуждения не имеет: до открытия PR правки для
+  человека нет. Открывается он тем же ходом, которым исполнитель говорит, что работу отдаёт, и
+  в ответе называется номером.
+- **Не готовое к слиянию открывается черновиком — `az repos pr create --draft true`.** Кнопка
+  завершения у черновика заблокирована самим хостингом, поэтому состояние «выложено на
+  обозрение» и состояние «можно вливать» перестают выглядеть одинаково. Черновиком идёт всё,
+  что ждёт прогона конвейера, доработки или ответа на вопрос; вопрос задаётся в самом PR.
+  Конвейер проверок черновика по умолчанию не запускает — до снятия черновика он молчит, и это
+  молчание за зелёный прогон не принимается.
+- **Черновик снимается отдельным вызовом — `az repos pr update --id <номер> --draft false`.**
+  Им исполнитель отвечает за готовность: проверки пройдены, доработок не осталось, работа
+  сходится с рабочим элементом. Снятие черновика и просьба влить — один ход, а не два разных
+  дня.
+- **Заведённый рабочий элемент подтверждается ответом очереди работ, а не выводом команды
+  заведения.** Команда отвечает за свои вызовы: она может завести элемент и не довести его до
+  доски, и её собственный разбор ошибок этот случай называет. Напечатанный номер значит «вызов
+  прошёл», а не «работа видна тому, кто по ней придёт». Спрашивается очередь — по номеру, одним
+  вызовом, — и ответ читается присутствием элемента на доске, его состоянием и исполнителем.
 - **Номер ветки и номер в заголовке PR сверяются на месте, а состояние — по доске.** Формат
   читается из текста команды и работает без сети; существование рабочего элемента, его
   состояние, исполнитель и то, что он ещё открыт, — только когда есть чем спросить. Нет сети
@@ -57,15 +100,26 @@ description: Правило под «Закон о поставке» для д
   элемент переводится в `Active`, PR открыт — в `Resolved`; делает это команда перевода, а не
   набор вызовов по памяти. Перевод идёт сразу за шагом, который его вызвал: очередь работ
   читают между шагами, а не после них.
+- **На доске стоят рабочие элементы, а не PR о них.** Доска показывает, что сделано и что
+  осталось; PR отвечает на другой вопрос — как именно сделано, — и открывается из элемента, где
+  связь с ним стоит сама. Здесь эта связь ставится при создании PR, поэтому отдельная карточка
+  не нужна вовсе, а заведённая живёт своей жизнью: состояния под неё нет, из очереди она не
+  уходит и остаётся в ней после слияния навсегда. Находит такие сверка очереди — строкой на
+  каждую.
+- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
+  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
+  не поднимает стенда, не снимает кадров и не собирает образов. Признак объявляется переменной
+  задания и считается один раз, а не переспрашивается в каждом условии. Пропущенный шаг виден в
+  прогоне пропущенным — молча выпавший читается как пройденный.
 - **Отставшее состояние находится сверкой очереди, а не глазами.** Сверка судит состояние по
-  отчёту в обе стороны: открытый PR при элементе не в разборе и разбор без открытого PR — оба
+  PR в обе стороны: открытый PR при элементе не в разборе и разбор без открытого PR — оба
   расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на доске нет.
 - **Задачи, чинящиеся одной правкой, сливаются до слияния ветки.** Вторая закрывается как
   дубликат, а недостающее из неё дописывается в первую. После слияния слить уже нельзя: ветка
   въехала, и откатывается она целиком.
 - **Работа, которую одним заходом не закрыть, помечена в двух местах, и они сверяются.** Метка
-  на доске и строка о заходах с передачей в линии работ говорят одно и то же двум читателям:
-  исполнитель открывает карточку раньше, чем линию, а планирует по линии. Одна пометка без
+  на доске и строка о заходах с передачей в замысле эпика говорят одно и то же двум читателям:
+  исполнитель открывает карточку раньше, чем замысел эпика, а планирует по замыслу. Одна пометка без
   другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
   законно не делится: пометка объёма правом делить не становится.
 - **Слияние в главную ветку выкатывает прод.** Фильтры путей конвейера покрывают документы
@@ -88,9 +142,9 @@ description: Правило под «Закон о поставке» для д
   ветке, а задание выкатки прибито условием к главной: прогон ради проверки доходит до сборок и
   там кончается. Прогон команд задания на своей машине его не покрывает: он проверяет команды,
   а не файл конвейера, — верность самого файла читается только по списку прогонов после пуша.
-- **Отчёт проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
+- **PR проверяется до слияния тем же конвейером, что и главная ветка.** Проверки и сборки
   образов идут на конвейере проверки PR, выкатка — нет: её держит условие по главной ветке у
-  своего задания, а образ отчёта в реестр не уезжает.
+  своего задания, а образ PR в реестр не уезжает.
 - **Расхождение прода с главной веткой видно сверкой очереди работ.** Рабочий элемент уходит из
   очереди слиянием, но слияние — ещё не прод: отказавшая выкатка не трогает ни элемент, ни его
   состояние, и заметить её неоткуда. Сверка спрашивает последний прогон главной ветки и судит
@@ -145,7 +199,7 @@ description: Правило под «Закон о поставке» для д
 
 Гард поставки стоит на командах агента, поэтому ветку, заведённую руками в редакторе, он не
 видит: имя такой ветки держится памятью. Требование от этого не слабеет — просто отдельной
-проверки под него не заводится: работа опознаётся заголовком рабочего элемента и отчёта, а это
+проверки под него не заводится: работа опознаётся заголовком рабочего элемента и PR, а это
 сверяется у всех. Сверка очереди имя ветки не судит вовсе: у открытого PR его не переименовать.
 
 Взятие задачи в работу не стережёт ничто: доска ветки не видит, а гард поставки её видит, но
@@ -191,7 +245,7 @@ description: Правило под «Закон о поставке» для д
 - **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
   записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
   работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
-  смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
 - **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** Прогон
   заводится и кончается на разборе файла, не начав ни одного задания: в списке он стоит
   отказом, а внутри нет ни задания, ни лога — читается только длительность. Поэтому список

package/assets/rules/git-workflow.github.md

@@ -22,7 +22,7 @@ description: Правило под «Закон о поставке» для д
 | задача                           | issue репозитория, заголовок `[<КЛЮЧ>-<номер>] <Что не так>`, исполнитель — учётная запись машинной работы; PR прикрепляется к нему строкой `Closes #<номер>` в теле                            |
 | очередь работ                    | борда GitHub Projects. К репозиторию она не привязана: `projectsV2` у него пуст, и задача попадает на борду только явным добавлением                                                            |
 | состояние задачи в очереди работ | колонка борды — поле «Status»: заведённая, взятая в работу, ждущая разбора. Имена колонок — в `implementation.md`; закрытая задача уходит из очереди мержем, а не переводом в последнюю колонку |
-| отчёт о задаче                   | заголовок PR `[<КЛЮЧ>-<номер>] <Что сделано>` — тот же номер, что у задачи, и её название, переведённое в сделанное; тип и область коммита сюда не идут                                         |
+| PR о задаче                      | заголовок PR `[<КЛЮЧ>-<номер>] <Что сделано>` — тот же номер, что у задачи, и её название, переведённое в сделанное; тип и область коммита сюда не идут                                         |
 | обсуждение правки                | разбор PR: ревьювер — владелец репозитория, исполнитель — учётная запись машинной работы, метки — те же, что у задачи                                                                           |
 | попадание правки в главную ветку | мерж PR; он же запускает выкатку — `.github/workflows/deploy.yml`                                                                                                                               |
 | образ того коммита               | `IMAGE_TAG=<sha>` в командах `docker compose` на сервере                                                                                                                                        |
@@ -36,6 +36,30 @@ description: Правило под «Закон о поставке» для д
 переносится между репозиториями, раскладка — нет, и путь, названный в правиле, врёт в первом
 же дереве, которое держит код иначе.
 
+## Ход
+
+Ход работы от задачи до слияния: где стоит гард, что двигает колонку очереди работ и чем
+работа кончается.
+
+```mermaid
+flowchart TD
+    A[Работа начинается] --> B[Задача заводится командой и встаёт в очередь работ]
+    B --> C[Ветка называется номером задачи; колонка двигается тем же движением]
+    C --> D{Правка готова}
+    D -->|Нет| C
+    D -->|Да| E[Главная ветка влита, набор гейта прогнан целиком]
+    E --> F{Ветка несёт номер задачи}
+    F -->|Нет| G[Гард поставки отбивает открытие: за правкой ничего не стоит в очереди]
+    F -->|Да| H[PR открывается; не готовое к слиянию идёт черновиком]
+    H --> I[Колонка задачи переходит в разбор, исполнитель берёт следующую задачу]
+    I --> J{Прогон и разбор кончились}
+    J -->|Прогон красный| K[Чинится в той же ветке]
+    K --> J
+    J -->|Зелено| L[Папка задачи разбирается последним коммитом, черновик снимается]
+    L --> M[Слияние нажимает человек: исполнитель просит и называет номер]
+    G --> B
+```
+
 ## Как закон применяется здесь
 
 - **Коммит в главную ветку отбивается гардом.** Гард ищет вызов коммита в любом месте команды
@@ -49,7 +73,7 @@ description: Правило под «Закон о поставке» для д
   разошедшейся ветки показывает ревьюверу свою правку вперемешку с чужой, а всё, что автор
   проверил до публикации, он проверил от основания, которого в главной ветке уже нет.
 - **Ключ задач задаётся один раз, и все три формы имени выводятся из него.** Заголовок задачи,
-  имя ветки и заголовок отчёта строит один и тот же ключ: команда заведения задачи собирает по
+  имя ветки и заголовок PR строит один и тот же ключ: команда заведения задачи собирает по
   нему заголовок, гард поставки достаёт по нему номер из имени ветки, сверка очереди — из
   заголовка. Форма ветки в профиле дерева пишется той же парой `<КЛЮЧ>-<номер>`, а не своей
   похожей: разойдясь, они не отказывают, а перестают узнавать номер, и проверка, искавшая
@@ -58,6 +82,11 @@ description: Правило под «Закон о поставке» для д
   же вызове и называет, где ключ задаётся. Умолчания у ключа нет намеренно: собранный из
   пустого значения заголовок `[-317]` не совпадает ни с чем, и сверка очереди помечает
   неправильно названной каждую задачу — настоящее расхождение тонет среди этих строк.
+- **Заведённая задача подтверждается ответом очереди работ, а не выводом команды заведения.**
+  Команда отвечает за свои вызовы: она может завести задачу и не довести её до борды, и её
+  собственный разбор ошибок этот случай называет. Напечатанный номер значит «вызов прошёл», а не
+  «задача видна тому, кто по ней работает». Спрашивается очередь — по номеру, одним вызовом, — и
+  ответ читается присутствием задачи на борде, её колонкой и исполнителем.
 - **Номер ветки и номер в заголовке PR сверяются на месте, а состояние задачи — по борде.**
   Формат читается из текста команды и работает без сети; существование задачи, её присутствие
   на борде, исполнитель и то, что она ещё открыта, — только когда есть чем спросить. Нет сети
@@ -67,15 +96,26 @@ description: Правило под «Закон о поставке» для д
   переставляется во взятые в работу, PR открыт — в ждущие разбора; делает это команда
   перевода, а не набор вызовов GraphQL по памяти. Перевод идёт сразу за шагом, который его
   вызвал: очередь работ читают между шагами, а не после них.
+- **На борде стоят задачи, а не PR о них.** Борда показывает, что сделано и что осталось; PR
+  отвечает на другой вопрос — как именно сделано, — и открывается из карточки задачи, где связь
+  с ним заполняется сама полем «Linked pull requests». Карточка PR живёт своей жизнью: колонки
+  под неё нет, из очереди она не уходит и остаётся в ней после слияния навсегда. Заводится она
+  либо встроенным правилом борды, либо рукой; и то и другое выключается, а накопившееся
+  снимается. Находит их сверка очереди — строкой на каждую.
+- **Конвейер судит по составу правки, а не гоняет всё подряд.** Шаги, которым нечего проверять,
+  пропускаются по признаку, посчитанному от главной ветки: ветка, не тронувшая ни строки кода,
+  не поднимает стенда, не снимает кадров и не собирает образов. Признак считается один раз и
+  объявляется выводом шага, а не переспрашивается в каждом условии. Пропущенный шаг виден в
+  прогоне пропущенным — молча выпавший читается как пройденный.
 - **Отставшая колонка находится сверкой очереди, а не глазами.** Сверка судит колонку по
-  отчёту в обе стороны: открытый PR при задаче не в разборе и разбор без открытого PR — оба
+  PR в обе стороны: открытый PR при задаче не в разборе и разбор без открытого PR — оба
   расхождения. Момента, когда задачу берут в работу, ей не видно: ветки на борде нет.
 - **Задачи, чинящиеся одной правкой, сливаются до мержа.** Вторая стирается вместе с номером,
   а недостающее из неё дописывается в первую. После мержа слить уже нельзя: ветка въехала, и
   откатывается она целиком.
 - **Работа, которую одним заходом не закрыть, помечена в двух местах, и они сверяются.** Метка
-  на борде и строка о заходах с передачей в линии работ говорят одно и то же двум читателям:
-  исполнитель открывает карточку раньше, чем линию, а планирует по линии. Одна пометка без
+  на борде и строка о заходах с передачей в замысле эпика говорят одно и то же двум читателям:
+  исполнитель открывает карточку раньше, чем замысел эпика, а планирует по замыслу. Одна пометка без
   другой лжёт молча, поэтому сверка очереди судит пару в обе стороны. Помечается только то, что
   законно не делится: пометка объёма правом делить не становится.
 - **Мерж в главную ветку выкатывает прод.** Исключения по путям покрывают только документы,
@@ -99,9 +139,9 @@ description: Правило под «Закон о поставке» для д
   которая его заводит или переносит, ручной запуск не покрывает. Прогон команд задания на своей
   машине не покрывает её тоже: он проверяет команды, а не файл конвейера, — верность самого
   файла читается только по списку прогонов после пуша.
-- **Отчёт проверяется до мержа тем же конвейером, что и главная ветка.** Проверки и сборки
+- **PR проверяется до мержа тем же конвейером, что и главная ветка.** Проверки и сборки
   образов идут на событии `pull_request`, выкатка — нет: её держит условие по главной ветке у
-  своего задания, а образ отчёта в реестр не уезжает.
+  своего задания, а образ PR в реестр не уезжает.
 - **Расхождение прода с главной веткой видно сверкой очереди работ.** Задача уходит из очереди
   мержем, но мерж — ещё не прод: отказавшая выкатка не трогает ни задачу, ни её колонку, и
   заметить её неоткуда. Сверка спрашивает последний прогон главной ветки и судит только
@@ -133,6 +173,21 @@ description: Правило под «Закон о поставке» для д
   сломана, она описывает вчерашний день. Сравнение веток пишется от `origin/main` целиком —
   смешав в одной команде удалённую ссылку для одной стороны и локальную для другой, промах
   изнутри выглядит правильным.
+- **Правка кода отдаётся человеку открытым PR, а не запушенной веткой.** Ветка в списке ветвей
+  ему не показывается, во входящие не приходит и обсуждения не имеет: до открытия PR правки
+  для человека нет. Открывается он тем же ходом, которым исполнитель говорит, что работу
+  отдаёт, и в ответе называется номером.
+- **Не готовое к слиянию открывается черновиком — `gh pr create --draft`.** Кнопка слияния у
+  черновика заблокирована самим хостингом, поэтому состояние «выложено на обозрение» и
+  состояние «можно вливать» перестают выглядеть одинаково. Черновиком идёт всё, что ждёт
+  прогона конвейера, доработки или ответа на вопрос; вопрос задаётся в самом PR.
+- **Черновик снимается отдельным вызовом — `gh pr ready <номер>`.** Им исполнитель отвечает за
+  готовность: проверки пройдены, доработок не осталось, работа сходится с задачей. Снятие
+  черновика и просьба влить — один ход, а не два разных дня.
+- **Мерж PR нажимает человек, а не исполнитель работы.** Кнопка и вызов слияния равны: запрет
+  на них один. Исполнитель сливает свой PR только тогда, когда человек сказал это прямо и про
+  этот PR; сказанное об одном PR на следующий не переносится, а молчание разрешением не
+  бывает. Работа кончается PR, с которого снят черновик, и в ответе называется его номер.
 - **Автор PR не может быть его ревьювером.** Запрос разбора на самого себя GitHub принимает и
   молча не создаёт — разбор при этом выглядит запрошенным.
 - **Метки, исполнитель и ревьювер PR ставятся вызовами `gh api`, а не `gh pr edit`.** На
@@ -141,6 +196,15 @@ description: Правило под «Закон о поставке» для д
 - **Борда правится запросом GraphQL по идентификатору проекта.** `gh project` с `--owner`
   отвечает `unknown owner type`, когда владелец борды — не та учётная запись, под которой
   идёт вызов.
+- **Почта машинного коммита копируется из компаньона, а не набирается по памяти.** Служебный
+  адрес GitHub — `<число>+<логин>@users.noreply.github.com`, и сопоставляется он по числу: логин
+  рядом с ним не сверяет никто. Коммит с чужим числом уезжает подписанным посторонним человеком,
+  а изнутри промах не виден — имя учётной записи в истории то самое. Ту же строку держит профиль
+  дерева, и гард поставки отбивает пуш при расхождении.
+- **Личность машинной записи подтверждается ответом хостинга, а не узнаванием строки.** Знакомый
+  вид строки подтверждением не бывает — промах выглядел знакомо. Спрашивается токеном самой
+  записи, ответом о себе: логин и число приходят вместе. Поиск по числу для ограниченной записи
+  отвечает «не найдено» и её собственным токеном, поэтому годится только ответ о себе.
 - **Сценарии гардов задают настройки git сами, а не берут их с машины.** Коммит во временном
   репозитории сценария наследует общий конфиг: если включена подпись, git идёт в агент ключей,
   а заблокированный агент роняет весь набор — со стороны это выглядит сломанным гардом. Автор,
@@ -154,7 +218,7 @@ description: Правило под «Закон о поставке» для д
 
 Гард поставки стоит на командах агента, поэтому ветку, заведённую руками в редакторе, он не
 видит: имя такой ветки держится памятью. Требование от этого не слабеет — просто отдельной
-проверки под него не заводится: работа опознаётся заголовком задачи и отчёта, а это сверяется
+проверки под него не заводится: работа опознаётся заголовком задачи и PR, а это сверяется
 у всех. Сверка очереди имя ветки не судит вовсе: у открытого PR его не переименовать.
 
 Взятие задачи в работу не стережёт ничто: борда ветки не видит, а гард поставки её видит, но
@@ -162,11 +226,11 @@ description: Правило под «Закон о поставке» для д
 работу вместо промаха. Держится это памятью и подсказкой, которую печатает команда заведения
 задачи. Отставшую колонку находит сверка очереди — но уже после того, как PR открыт.
 
-Свежесть самой вершины главной ветки гард не проверяет: он судит по тому, что лежит в дереве, и
-вершину недельной давности от сегодняшней не отличает. Сетевой вызов сюда не заводится по той же
-причине, что и выше, — он падал бы вместе со связью. Поэтому гард ловит ветку, отставшую
-заведомо, а `git fetch` перед вливанием стоит первым пунктом чеклиста и держится тем же, чем
-держатся остальные его пункты.
+Свежесть самой вершины главной ветки гард спрашивает вторым ярусом — тем же приёмом, что и
+состояние задачи: есть чем спросить, спрашивает; нет сети или доступа — пропускает молча.
+Первый ярус при этом остаётся, и работает он без сети: локальная ссылка отвечает на вопрос
+«отстала ли ветка от того, что уже лежит в дереве», удалённая — на вопрос «не протухла ли сама
+ссылка». Без второго яруса молчание гарда значило лишь первое, а читалось как второе.
 
 ## Паттерны
 
@@ -198,7 +262,7 @@ description: Правило под «Закон о поставке» для д
 - **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
   записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
   работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
-  смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
 - **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** GitHub
   заводит такой прогон и на ветке, на которую ни один триггер не подписан: в списке он стоит
   отказом, а внутри у него нет ни задания, ни лога — читается только длительность. Поэтому