@rt-tools/agent-kit 0.8.1 → 0.8.3

package/assets/hooks/waiting-turn-guard.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# rt-hook: Stop
+# Гард ожидания: ход, в котором открыт PR, не заканчивается, пока в нём не было ни одного
+# действия по следующей задаче. Stop.
+#
+# Зачем именно так. Статья «ожидание прогона работой не занимают» держится памятью исполнителя, и
+# держится плохо: образец сообщения владельцу кончается фразой о следующей задаче, а фраза
+# исполняется как обещание — заход произносит её и кончает ход. Ход, в котором не сделано ничего,
+# ничем себя не выдаёт: ни правкой файла, ни командой, — и промах виден только владельцу, только
+# по тому, что работа не двигается, и только когда он спросит прямо.
+#
+# Признак берётся из хода, а не из сети. Спросить хостинг об открытых PR было бы точнее, но
+# сетевой вызов на завершении хода падает вместе со связью и отбивал бы работу вместо промаха.
+# Поэтому судится пара: в ходе был вызов открытия PR — и в том же ходе было действие по
+# следующей задаче.
+#
+# Что считается действием: заведение задачи, заведение ветки, перевод колонки очереди работ,
+# заведение папки задачи. Набор открыт и пополняется правкой — полнота его открытый вопрос, а не
+# обещание.
+#
+# Чего гард не судит. Ход, в котором PR не открывали, — здесь он молчит: пустой ход неотличим
+# от хода, которому нечего было делать. Это известная его граница.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: при любой ошибке, нехватке `jq`, отсутствии записи хода и повторном
+# заходе ход РАЗРЕШАЕТСЯ (exit 0). Сломанный гард не имеет права заклинить разговор.
+
+input="$(cat 2>/dev/null)"
+[ -z "$input" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Повторный заход по тому же ходу не судится: гард сказал своё один раз и отпускает.
+active="$(printf '%s' "$input" | jq -r '.stop_hook_active // false' 2>/dev/null)"
+[ "$active" = "true" ] && exit 0
+
+transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null)"
+[ -z "$transcript" ] && exit 0
+[ -f "$transcript" ] || exit 0
+
+# Открытие PR у каждого хостинга своё, и гард переносится между ними целиком: набор называет все
+# три формы, а не ту, что стоит в этом дереве. Правка тела PR сюда не входит — она не открывает
+# ничего.
+opened_re='gh[^|;&]*pr[[:space:]]+create|api[^|;&]*-X[[:space:]]+POST[^|;&]*/pulls|glab[^|;&]*mr[[:space:]]+create|az[[:space:]]+repos[[:space:]]+pr[[:space:]]+create'
+
+# Первое действие по следующей задаче. Заведение папки стоит здесь наравне с командами: работа
+# по уже заведённому номеру начинается именно с неё.
+moved_re='task:new|task:move|checkout[[:space:]]+-b|docs/tasks/'
+
+# Ход — это всё, что записано после последнего настоящего ввода владельца. Ответ инструмента
+# приходит той же ролью, поэтому строки с `tool_result` вводом не считаются.
+#
+# Хвост в 400 строк: запись хода растёт всю сессию, а судится только последний ход.
+verdict="$(tail -n 400 "$transcript" 2>/dev/null | jq -s -r --arg opened "$opened_re" --arg moved "$moved_re" '
+    def is_input:
+        .type == "user"
+        and (((.message.content // []) | if type == "array"
+                then ([.[] | select(.type == "tool_result")] | length)
+                else 0 end) == 0);
+
+    (map(is_input) | rindex(true)) as $i
+    | (if $i == null then [] else .[$i:] end) as $turn
+    | [$turn[] | select(.type == "assistant") | (.message.content // [])[] | select(.type == "tool_use")] as $uses
+    | ($uses | map((.input.command // "")) | join("\n")) as $ran
+    | ($ran | test($opened; "i")) as $opened_pr
+    | ($ran | test($moved; "i")) as $went_on
+    | if $opened_pr and ($went_on | not) then "owe" else "pass" end
+' 2>/dev/null)"
+
+[ "$verdict" = "owe" ] || exit 0
+
+reason="BLOCKED by waiting-turn-guard: в этом ходе открыт PR, а действия по следующей задаче в нём нет ни одного. Ожидание чужого шага заходом не занимают: прогон идёт на стороне и быстрее от взгляда на него не становится.
+
+Сказать «беру следующую задачу» — не то же самое, что взять её: фраза живёт до конца хода, а работа не двигается, и заметить это может только владелец.
+
+Тем же ходом делается первое действие по следующей задаче — заведение задачи, ветки или папки:
+
+    npm run task:new -- --title '<Что не так>' --slug <slug>
+    git checkout -b <КЛЮЧ>-<номер>-<slug>
+
+Конец прогона узнаётся возвратом фоновой команды, а не взглядом на страницу.
+
+Гард судит один ход: следующий заход не отбивается."
+
+jq -n --arg r "$reason" '{decision:"block",reason:$r}' 2>/dev/null \
+    || printf '{"decision":"block","reason":"waiting-turn-guard: PR открыт — тем же ходом берётся следующая задача."}\n'
+
+exit 0

package/assets/hooks/window-fill-guard.sh

@@ -131,7 +131,7 @@ case "$tool" in
         esac
         ;;
     Bash | mcp__webstorm__execute_terminal_command)
-        # Поставка и сверки: коммит, пуш, отчёт, колонка задачи, состояние дерева. Список
+        # Поставка и сверки: коммит, пуш, PR, колонка задачи, состояние дерева. Список
         # дописывается профилем дерева — клиент хостинга и имена команд у каждого свои.
         if rt_needs rt_handoff_allowed_cmd window-fill-guard && rt_handoff_allowed_cmd "$cmd"; then
             allowed=1

package/assets/laws/delivery.md

@@ -10,6 +10,18 @@
   очередь не попала, никто не видит, и работа за ней не планировалась.
 - **Правка попадает в главную ветку только через отдельную ветку.** Прямая запись в главную
   лишает правку и обсуждения, и возможности откатить её одним движением.
+- **В очереди работ стоят задачи, а не PR о них.** У задачи и её PR один номер и одна судьба,
+  поэтому вторая карточка о той же работе ничего не добавляет — она удваивает очередь и врёт о
+  её длине. Читают очередь затем, чтобы увидеть, что сделано и что осталось; PR отвечает на
+  другой вопрос — как именно сделано, — и попадают в него из карточки задачи, где связь с ним
+  и так стоит. Карточка PR при этом живёт своей жизнью: закрывается позже задачи, висит в
+  очереди после слияния и остаётся в ней навсегда, потому что колонки под неё нет.
+- **Проверка не гоняет того, что правка не может сломать.** Набор, одинаковый для любой правки,
+  выглядит строгим, а работает наоборот: прогон, который длится вдесятеро дольше нужного, учат
+  не ждать, а обходить. Состав набора выводится из состава правки — из того, что она задела, а
+  не из того, кем она названа; правка, не тронувшая ни строки кода, не собирает образов и не
+  снимает кадров. Пропущенное при этом называется пропущенным: молча выпавший шаг читается как
+  пройденный.
 - **У задачи одна ветка, у ветки одна задача.** Откат снимает всё, что въехало этой веткой,
   разом: две задачи в ней откатятся только вместе, а задача, въехавшая двумя ветками, после
   отката одной останется наполовину сделанной — и в очереди работ этого не видно. Работа,
@@ -28,10 +40,10 @@
   своим номером, а то, чего в первой не было, дописывается в неё до этого. Две строки об
   одной работе хуже дыры в нумерации: по ним потом не понять, что сделано, а что нет. Слить
   их можно, пока правка не въехала в главную ветку; после — обе остаются как есть.
-- **Задача, ветка под неё и отчёт о сделанном несут один и тот же номер в своих названиях.**
+- **Задача, ветка под неё и PR о сделанном несут один и тот же номер в своих названиях.**
   Иначе одну работу приходится узнавать по тексту названия, а в списке из полусотни строк это
   делается по памяти и с ошибками.
-- **Номер пишется всюду одинаково: ключ задач, дефис, номер.** Заголовок задачи и отчёта
+- **Номер пишется всюду одинаково: ключ задач, дефис, номер.** Заголовок задачи и PR
   начинается с этой пары в квадратных скобках, имя ветки — с неё же. Одна форма, а не три
   похожих, потому что номер читают не только глазами: из имени ветки его достаёт гард, из
   заголовка — сверка очереди. Формы, выведенные порознь, расходятся молча и не отказывают, а
@@ -46,9 +58,9 @@
   ничьей: по очереди работ не видно, кто её взял, и заведённая по ходу правка теряется среди
   чужих.
 - **Состояние задачи в очереди работ отвечает тому, что с ней происходит.** Взятая в работу
-  видна взятой, а та, отчёт по которой ждёт разбора, — ждущей разбора. Иначе очередь показывает
+  видна взятой, а та, PR по которой ждёт разбора, — ждущей разбора. Иначе очередь показывает
   один и тот же вид у нетронутого, у делаемого прямо сейчас и у сделанного: работа берётся
-  второй раз, а отчёт стоит неразобранным, пока про него не вспомнят. Состояние переставляется
+  второй раз, а PR стоит неразобранным, пока про него не вспомнят. Состояние переставляется
   в тот момент, когда работа переходит на следующий шаг, а не приводится в порядок потом:
   очередь читают между этими моментами, а не после них.
 - **Попадание правки в главную ветку означает выкатку.** Всё, от чего правка зависит снаружи
@@ -71,10 +83,32 @@
   иначе «сошлось» значит в этих двух местах разное.
 - **Документ едет вместе с правкой, которую он описывает.** Ни сборка, ни проверки текстов
   не читают, поэтому расхождение копится молча и потом выглядит действующей справкой.
-- **Отчёт о сделанном остаётся верным до самого слияния.** Он описывает дерево на день, когда
+- **Работа, меняющая код, кончается открытым PR.** PR — единственное место, где человек видит
+  правку целиком, отвечает на неё и вливает её; коммит в ветке и запушенная ветка этого места
+  не заменяют. Пока PR не открыт, работа сделанной не считается, сколько бы её ни было в
+  истории ветки: разбор по ней невозможен, а человек о ней не знает. Открывается PR тем же
+  ходом, которым исполнитель говорит, что работу отдаёт, — а не следующим заходом и не по
+  напоминанию.
+- **PR, не готовый к слиянию, помечается черновиком.** Открытый PR читается как приглашение
+  влить, и человек нажимает слияние, не спрашивая, кончилась ли работа. Черновик разводит два
+  состояния, которые иначе выглядят одинаково: правка выложена на обозрение — и правка готова
+  поехать в главную ветку. Помечается им всё, что ждёт прогона, доработки или ответа на
+  вопрос; вопрос при этом задаётся в самом PR, а не остаётся в голове исполнителя.
+- **Снятие черновика — отдельный ход, и им исполнитель отвечает за готовность.** Черновик
+  снимается тогда, когда проверки пройдены, доработок не осталось и работа сходится с тем,
+  ради чего заводилась задача. Пока он стоит, молчание исполнителя значит «ещё не готово», и
+  человек ничего не должен переспрашивать; после снятия оно значит «можно вливать», и цена
+  ошибки здесь — правка в главной ветке.
+- **PR о сделанном остаётся верным до самого слияния.** Он описывает дерево на день, когда
   его написали, а разбора ждёт днями: за это время главная ветка вливается в ветку, и
-  утверждение отчёта о соседних файлах становится неправдой молча — тел отчётов не читает ни
-  одна проверка. Всё, что вливается в ветку после публикации отчёта, — повод перечитать его.
+  утверждение PR о соседних файлах становится неправдой молча — тел PR не читает ни
+  одна проверка. Всё, что вливается в ветку после публикации PR, — повод перечитать его.
+- **PR в главную ветку вливает человек.** Слияние — последний момент, когда разбор ещё
+  возможен: после него правка стоит в главной ветке, работа ушла к следующей задаче, и
+  вернуться к ней уже некому. Исполнитель работы вливает свой PR только по прямому слову
+  человека и только про названный PR; молчание разрешением не бывает, а слово, сказанное об
+  одном PR, на следующий не переносится. Иначе разбор проходит тот, кого разбирают, и
+  очередь PR выглядит разобранной, не будучи ею.
 - **Слияние в главную ветку ещё не означает, что правка доехала.** Отказ выкатки не трогает ни
   задачу, ни очередь работ, поэтому расхождение главной ветки с тем, что работает, обязано быть
   видно там, где очередь читают. Иначе следующие работы вливаются поверх поломки, которую не

package/assets/laws/project-documentation.md

@@ -56,3 +56,42 @@
   знает само дерево, а не текст, приехавший в него. Утверждение, сказанное безусловно, врёт тем
   увереннее, что печатает его сам инструмент, — и поправить его дерево не может, если правки на
   месте у такого текста не предусмотрено.
+- **Принятое решение становится пунктом слоя правил, а не записью о прошлом.** Записанное
+  описанием прошлого перестаёт действовать в тот же день: описания прошлого не приходят в
+  контекст работы, читаются как история и ничего не требуют. Следующая работа принимает то же
+  решение заново — и принимает иначе, потому что доводов первого уже не видит.
+- **У решения есть слой, и он выбирается по тому, о чём решение говорит.** Что должно быть
+  верно в продукте — статья закона. Каким приёмом это делается здесь — пункт правила. Готовый
+  код и порядок действий — паттерн. Решение, положенное не в свой слой, находится только тем,
+  кто уже знает, что оно есть.
+- **Описание прошлого объясняет состоявшийся переезд, а не держит действующее требование.**
+  Разница видна вопросом: перестанет ли текст быть верным, если завтра всё переделать. Рассказ
+  о том, как и почему однажды перенесли, — прошлое; требование «делай так» — нет, и место ему
+  в слое правил.
+- **Признак, по которому решение относят к прошлому, записан заранее и один на все работы.**
+  Выводимый каждой работой заново, он назначается тем, кому мешает: под конец работы дешевле
+  назвать прошлым всё, что осталось разобрать.
+- **Раздел решений в описании домена — временное место, а не постоянное.** Пока решение там,
+  оно действует только для того, кто открыл этот файл. Разросшийся раздел — признак того, что
+  правило под него не заведено, а не того, что домен сложный.
+- **Работа, которая переносит решения, называет для каждого, куда оно ушло.** Иначе по
+  описанию прошлого не отличить решение, ставшее правилом, от решения, потерянного при
+  переносе: оба выглядят одинаково — записью, на которую никто не ссылается.
+- **Текст, раздаваемый наружу, судится не слабее своей копии у потребителя.** Требование,
+  стоящее к копии и не стоящее к источнику, находит промах у того, кто его не делал и починить
+  не может: до потребителя промах доезжает целым, а краснеет уже там.
+- **Редакция текста, которую это дерево не выбрало, судится наравне с выбранной.**
+  Непрочитанная редакция расходится с прочитанной молча, и узнаёт об этом первый, кто её
+  выберет, — то есть тот, у кого нет ни истории расхождения, ни повода его искать.
+- **Набор обязательных разделов объявлен отдельно, и образец ему не хозяин.** Образец —
+  черновик для того, кто заводит текст, и стареет он первым. Набор, выведенный из образца, либо
+  объявляет расхождением весь корпус разом, либо не замечает ничего.
+- **Требование, которого никто не формулировал, молчит, а не отказывает.** Отказ на предмете
+  без объявленного требования гасят списком исключений, а список исключений через месяц
+  становится рабочим путём — и гасит вместе с шумом то, ради чего проверка заводилась.
+- **Два текста об одном либо говорят одно, либо один из них неправ.** Согласие текстов между
+  собой не следует ни из целостности ссылок, ни из полноты разделов: оба проходят любую такую
+  проверку, а исполнитель берёт тот, который прочитал раньше. Ищется это чтением — считать
+  здесь нечего.
+- **Изображение правится тем же изменением, что и текст, который оно изображает.** Разойдясь,
+  схема и проза остаются читаемыми обе, и первым это замечает тот, кто пошёл по схеме.

package/assets/laws/verifiability.md

@@ -33,7 +33,7 @@
 - **Успешный ответ команды означает, что она отработала, а не что нужное состояние
   наступило.** Часть запросов выполняется наполовину, и об отклонённой части в ответе ничего
   нет: по коду возврата такой вызов не отличить от исполненного. Поэтому результат читают
-  отдельным запросом, и в отчёт идёт то, что прочитали, а не то, что заказывали.
+  отдельным запросом, и в PR идёт то, что прочитали, а не то, что заказывали.
 - **Служба считается поднятой, когда она выполнила задание, а не когда сообщила о
   готовности.** Сообщение о готовности говорит лишь, что служба себя объявила: та, которой не
   досталось ни одного задания, выглядит в нём точно так же, как работающая. Проверяются обе
@@ -47,6 +47,11 @@
   выключают в настройке инструмента, а не обходят в каждом месте.** Обход приходится повторять
   столько раз, сколько таких мест, и ни в одном из них не написано, зачем он: со стороны это
   выглядит ошибкой автора, а не решением.
+- **Красная проверка означает неверный код, а не неверную проверку.** Место, выведенное
+  из-под проверки затем, чтобы она замолчала, чинит показание, а не то, на что она указала:
+  код остаётся прежним, а сигнала о нём больше нет ни у кого. Список известного накоплен к
+  дню заведения проверки и только сокращается; несогласие с самой проверкой — вопрос к
+  владельцу, а не строка в списке.
 - **Польза правила подтверждается наблюдением за тем, как им пользуются, а не мнением о нём.**
   Правило, которого не открыли ни разу, и правило, на котором держится половина работы, в тексте
   выглядят одинаково — и правится первым обычно то, о чём вспомнили, а не то, что мешает.

package/assets/laws/work-conduct.md

@@ -20,7 +20,7 @@
 - **Остановка называется первой строкой.** Сообщение, которым исполнитель останавливается,
   начинается с того, чего он ждёт и что будет, если ответа не будет. Замеры, находки и разбор
   к этому моменту уже записаны в ход работы — в сообщении владельцу они лишние. Чем подробнее
-  отчёт, тем надёжнее вопрос в нём тонет, и владелец переспрашивает, почему работа стоит.
+  PR, тем надёжнее вопрос в нём тонет, и владелец переспрашивает, почему работа стоит.
 - **Владельцу не задаётся вопрос, ответ на который уже записан.** Записанное читают до
   разговора, а не вместо ответа: вопрос о том, что уже решено, обесценивает и остальные.
 - **Вопрос владельцу задаётся после того, как ответ искали в дереве.** Что лежит в дереве,
@@ -31,6 +31,11 @@
   «здесь нет», «этого не заводили», «такого файла не бывает» — произносится только как вывод
   команды. Не проверенное отрицание опаснее вопроса: вопрос владелец поправит, а факт от
   исполнителя примет на веру, потому что тот в дерево смотрит.
+- **Отрицание, полученное одним источником, отрицанием не является.** Ответ «не найдено», отказ
+  в доступе и пустой список говорят о правах спрашивающего, а не о предмете: тот же вопрос,
+  заданный оттуда, где предмет виден, отвечает обратным. Сказать «этого нет» можно только после
+  второго источника — иначе исполнитель называет владельцу собственные права, приняв их за
+  устройство мира.
 - **Решение, однажды записанное, действует, пока его не отменили, и читается до того, как
   принимается заново.** Отменённое решение следа в работе не оставляет — по результату не
   видно ни того, что его принимали, ни того, что от него отказались. Принятое заново оно
@@ -58,7 +63,7 @@
   пересказ он даёт по своей памяти, а не по ходу работы, и следующий заход начинает с чужой
   картины.
 - **Замысел и ход работы — разные записи.** Замысел — то, с чем сверяют результат при
-  приёмке; правленный по ходу, он перестаёт отличаться от отчёта, и приёмке сверять нечего.
+  приёмке; правленный по ходу, он перестаёт отличаться от PR, и приёмке сверять нечего.
 - **Сделанное отмечается в одном месте.** Две записи об одном разъезжаются молча, и после
   этого ни по одной не видно, что осталось.
 - **Решение, принятое по ходу работы, записывается вместе с причиной.** Без причины оно
@@ -66,7 +71,7 @@
 - **Граница работы названа до её начала.** Не названная вслух граница не существует: правка
   расползается на соседнее, и снимать её приходится вручную.
 - **Действия, которые исполнитель не делает сам, названы списком.** Всё, что уходит за
-  пределы рабочего дерева или не откатывается — запись в общий репозиторий, публикация, отчёт,
+  пределы рабочего дерева или не откатывается — запись в общий репозиторий, публикация, PR,
   правка общего документа, — делается по слову владельца, и слово это даётся на действие, а не
   на работу целиком. Не названная списком граница выводится из общих слов: «делай, что нужно
   по плану» прочитывается как разрешение на всё, что в плане подразумевалось.
@@ -104,3 +109,78 @@
 - **У предложенной правки правил назван адрес: сам слой правил, имена этого дерева или его
   надстройка.** Без адреса правку кладут туда, где она видна автору, — то есть в своё дерево, —
   и общее оседает в одном месте, оставаясь неизвестным всем остальным.
+- **Предложение, о котором владелец сказал вслух, уходит наружу в тот же ход.** Написанное и не
+  отправленное лежит в дереве неотличимо от отправленного: своей записи в слое правил у него
+  нет, и владелец читает работу сделанной, пока не спросит прямо. Слово владельца о предложении
+  — «отправь», «заведи», «напиши» — распоряжение, а не тема разговора; показ того, что уехало
+  бы, отправкой не является и следа наружу не оставляет.
+- **Неудобство отправки — повод сказать о нём, а не повод не отправить.** Довод исполнителя
+  против уже принятого решения владельца остаётся доводом: он называется вслух, работа при этом
+  идёт. Отложить исполненное решение может только владелец; отложенное собственным доводом
+  выглядит для него сделанным, и цену этого он узнаёт последним.
+- **Работа, из которой видно серию задач, объявляется эпиком до первой из них.** Объявляется
+  дважды: карточкой в очереди работ и замыслом рядом с ней. Не объявленная серия существует
+  только в голове того, кто её задумал: следующий заход видит разрозненные задачи, порядка между
+  ними не находит и берёт ту, что ближе лежит.
+- **Замысел эпика называет разрабатываемую возможность, состав задач и их порядок.** Состав без
+  порядка порядком не является: две задачи, у которых порядок держался пониманием, ушли в работу
+  наоборот, и вторая переделывалась под первую. Возможность, названная одним словом, через неделю
+  читается каждым по-своему.
+- **Порядок задач эпика назначается на планировании и держится до его конца.** Пересмотр по ходу
+  — решение владельца, записанное там же, где идёт работа. Порядок, назначаемый заново перед
+  каждой задачей, назначает тот, кому ближе, и эпик кончается там, где надоел.
+- **Заход исполнителя не кончается вместе с задачей.** Конец задачи — не признак остановки:
+  остановиться позволяет только предел заполнения окна. Заход, закрытый на готовой задаче,
+  оставляет владельцу пустое место и стоит целого захода на возвращение к тому, что и так было
+  под рукой.
+- **Работа, отданная на разбор, освобождает исполнителя, а не останавливает его.** Отданное на
+  разбор ждёт владельца, а не машину: следующая задача эпика берётся тем же движением, которым
+  предыдущая ушла на разбор.
+- **Ожидание машины работой не занимают.** Проверка, идущая на стороне, не спрашивает
+  исполнителя ни о чём и не идёт быстрее оттого, что он на неё смотрит. Пока она идёт, работа
+  продолжается: берётся следующая задача, а к проверке возвращаются тем ходом, которым читают
+  её конец. Заход, проведённый в ожидании, стоит ровно столько же, сколько заход, в котором
+  сделана задача, — и не даёт ничего.
+- **Ожидание, которое всё-таки останавливает работу, называется владельцу отдельно и прямо.**
+  Есть случаи, где дальше и вправду не пройти: следующая задача стоит на неразобранной, или
+  правка ждёт решения, которого нет ни у кого, кроме владельца. Тогда исполнитель говорит три
+  вещи — что именно стоит, чего оно ждёт и что владелец может с этим сделать: разобрать работу
+  первой или снять ожидание своим словом. Сказанное вперемешку с отчётом о сделанном не
+  читается: остановка называется отдельно от всего остального.
+- **Разбор закрытой работы идёт своим ходом и работу не задерживает.** Он смотрит на то, что
+  видно только заходу, который работу вёл, поэтому пропустить его нельзя; но и держать ради
+  него следующую задачу незачем — он ничего не спрашивает у исполнителя, пока идёт. Его находки
+  записываются туда, где их найдут после слияния работы, и показываются владельцу целиком, а не
+  уезжают наружу сами: что из них станет правкой, решает он.
+- **Отдав работу на разбор, исполнитель называет, чего ждёт и что сделает следом.** Владелец
+  видит не голову исполнителя, а страницу работы: зелёная проверка и доступное действие
+  читаются как «всё кончено». Названное вслух ожидание — единственное, что отличает «жду
+  проверок, потом уберу за собой» от «готово, забирай». Не названное, оно не существует, и
+  владелец действует по тому, что видит.
+- **Работа не считается готовой, пока исполнитель не сказал этого прямо.** Готовность объявляет
+  тот, кто работу вёл, — отдельной просьбой и про эту работу. Зелёные проверки готовностью не
+  являются: они говорят, что не сломано, и молчат о том, осталось ли что-то сделать. Молчание
+  исполнителя владелец читает как готовность, и между двумя прочтениями теряется всё, что
+  стояло после разбора.
+- **Уборка за работой идёт до того, как о готовности сказано.** Всё, что работа обязана убрать
+  за собой, убирается раньше просьбы включить её в общее дерево, а не после согласия. После
+  включения убирать уже некому: работа перешла к следующей задаче.
+- **Пока эпик не кончился, следующая работа не выбирается, а берётся.** Выбор, предложенный
+  владельцу при назначенном порядке, — это просьба назначить его заново: он уже назначен, и
+  предлагать его повторно значит отменять собственное планирование.
+- **Замеченное по ходу и к эпику не относящееся становится задачей в очереди работ, а не работой
+  сейчас.** Отвлечение выглядит дешёвым ровно до того, как окажется, что вместе с ним уехала
+  правка соседнего домена: эпик при этом стоит, а откатывать приходится обе работы.
+- **Эпик кончается, когда кончились его задачи, а не когда стало непонятно, что дальше.**
+  Непонятно бывает от того, что замысел не открыли: он лежит и держит решения, которых в коде не
+  видно.
+- **Положение эпика показывается владельцу таблицей — в передаче и при остановке за его
+  решением.** Это два момента, когда владелец смотрит на работу снаружи: в первый он забирает её
+  в новый заход, во второй решает, куда её вести. Порядок задач при этом лежит в замысле, а
+  замысел ни там, ни там не открывают — передача пересказывает один заход, вопрос называет одну
+  развилку, и по обоим не видно ни сделанного, ни оставшегося.
+- **Таблица показывает все задачи эпика разом — закрытые, текущую и назначенные.** Строка на
+  задачу: место по порядку, задача, состояние; текущая отличается от остальных на вид. Порядок у
+  закрытых фактический, у будущих назначенный, и расхождение между ними тоже утверждение — оно
+  говорит, что порядок пересматривали. Перечень одних оставшихся не показывает, чего работа
+  стоила; перечень одних закрытых не показывает, сколько ещё впереди.

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

@@ -2,7 +2,7 @@
 name: git-workflow-commit
 kind: pattern
 rule: git-workflow
-description: Паттерн правила git-workflow для дерева в Azure DevOps. Брать на заведение рабочего элемента, ветки, коммит, пуш и создание PR — заведение элемента со всеми шагами, перевод по состояниям, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, привязка PR к элементу, ревьювер, исполнитель и метки, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+description: Паттерн правила git-workflow для дерева в Azure DevOps. Брать на заведение рабочего элемента, ветки, коммит, пуш и создание PR — заведение элемента со всеми шагами, перевод по состояниям, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, привязка PR к элементу, ревьювер, исполнитель и метки, образец тела PR с разделом об оставшемся шаге, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
 ---
 
 # Ветка, коммит и PR
@@ -43,6 +43,14 @@ az boards work-item update --id <номер> --title '[<номер>] …'   # н
 Номер в заголовок руками не пишется — он известен только после создания, и команда дописывает
 его сама.
 
+Заведение кончается не выводом команды, а ответом очереди работ. Команда спрашивает её сама и
+печатает прочитанное — присутствие на доске, состояние, исполнителя; отсутствие кончает её
+ненулевым кодом. В комментарий, в тело PR и в замысел идёт этот ответ, а не напечатанный
+номер: номер говорит «вызов прошёл», а не «работа видна тому, кто по ней придёт».
+
+Заведения, идущие подряд, проверяются не по последнему, а сверкой очереди целиком: промах у них
+общий, и по одному элементу он не виден.
+
 Чем сверить, что очередь работ в порядке:
 
 ```bash
@@ -161,6 +169,35 @@ PR       [86] Письмо владельцу с незаполненным ад
 Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
 коммита, и там его сверяет `commitlint`.
 
+## Не готовое к слиянию открывается черновиком
+
+Правка кода отдаётся человеку открытым PR: запушенная ветка ему не показывается нигде. Открытый
+PR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
+черновиком — завершение у черновика хостинг блокирует сам:
+
+```bash
+AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create --draft true --title '[<КЛЮЧ>-86] …' \
+    --description "$(cat тело.md)"
+```
+
+Конвейер проверок у черновика по умолчанию не запускается: молчание прогона за зелёный прогон
+не принимается, и набор гоняется на своей машине либо запуском вручную.
+
+Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
+задаётся в самом PR, а не остаётся в голове исполнителя: человек читает PR, а не переписку
+захода.
+
+Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
+решение готово:
+
+```bash
+AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr update --id 86 --draft false
+```
+
+До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
+черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
+ждёт разбора ровно так же, как не снятый.
+
 ## PR привязывается к элементу при создании
 
 Привязка задаётся флагом, а не правкой после: у токена может не быть права править чужой
@@ -187,7 +224,47 @@ az repos pr update --id 205 --description "$(cat тело.md)"
 ```
 
 Правка описания переписывает его целиком. Тело перечитывается всякий раз, когда в ветку что-то
-влилось после публикации: отчёт утверждает про дерево, а дерево с тех пор изменилось.
+влилось после публикации: PR утверждает про дерево, а дерево с тех пор изменилось.
+
+## Образец тела PR
+
+Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
+оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
+заголовок читаются одинаково, а значат разное.
+
+```markdown
+Закрывает рабочий элемент 86.
+
+## Что сделано
+
+- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
+
+## Чем подтверждено
+
+- <проверка>: <её вывод одной строкой>
+- Не гонялось: <что в набор не вошло и почему>
+
+## Оставшийся шаг
+
+После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
+вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
+```
+
+Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
+— в тот ход, которым папка разбирается и снимается черновик:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
+```
+
+Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
+сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
+не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
+
+Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
+заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
 
 ## Состояние PR читается, а не додумывается
 
@@ -236,7 +313,10 @@ npm run task:move -- 86 in-review
    `browser-verification-measure`.
 9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** —
    паттерн `seo-verify`.
-10. **PR привязан к рабочему элементу**, ревьювер и исполнитель стоят.
+10. **PR привязан к рабочему элементу**, ревьювер и исполнитель стоят, а тело собрано по
+    образцу — разделы «Что сделано», «Чем подтверждено» и «Оставшийся шаг». Раздел оставшегося
+    шага к этому моменту говорит, что шагов не осталось: черновик снимается после разбора
+    папки, а не до него.
 11. **Заголовок PR несёт номер элемента и называет работу сделанной:** `[<номер>] <Что
 сделано>`, тем же номером, что стоит у элемента и в имени ветки.
 12. **Очередь работ сходится** — `npm run check:board`.
@@ -248,7 +328,7 @@ npm run task:move -- 86 in-review
 15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
     теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
     снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
-    отчёт.
+    PR.
 
 Сразу после публикации элемент переводится в разбор, и сверка очереди прогоняется ещё раз: до
 открытия PR состояние она не судит, а после открытия расхождение видит.