@rt-tools/agent-kit 0.17.0 → 0.18.0

package/assets/hooks/work-start-guard.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# rt-hook: Stop
+# Требует: hooks/deny-tail.sh, hooks/profile-check.sh
+# Гард начала работы: ход, правивший код приложения, не заканчивается, пока владелец в этом же
+# ходе о работе не просил. Stop.
+#
+# Зачем именно так. Статья «заход работу не начинает сам» держится памятью исполнителя, и
+# держится плохо: заход, открывшийся после чистки контекста, получает от хука запуска состояние
+# незаконченной работы и замысел с этапами — и оба говорят, что делать, если работать. О том,
+# работать ли, не говорит ни один. Строка с путём к файлу, присланная владельцем, прочитана как
+# поручение, и заход правит полсотни файлов, которых у него никто не просил.
+#
+# Соседние гарды этого не ловят, и не по недосмотру: каждый судит своё. Гард замысла требует
+# замысел на диске — он лежит; гард эпика отбивает чужую задачу — задача своя; гард разговора
+# судит ход, в котором задан вопрос, — а вопроса не задали ровно потому, что решили не
+# спрашивать. Все три судят предмет правки и её порядок, и ни один не спрашивает, кто эту
+# правку заказал.
+#
+# Просьба ловится формой, а не смыслом. Смысл машине не виден, и гард, взявшийся его понимать,
+# отбивал бы работу по настроению; поэтому судится обратное — то, что просьбой не бывает ни при
+# каком прочтении: пустая реплика, одно слово и путь к файлу. Всё остальное считается просьбой,
+# и это выбрано намеренно: ложный отказ здесь стоит дороже пропуска — он останавливает работу,
+# которую владелец заказал.
+#
+# Код приложения узнаётся признаком дерева `rt_is_app_code` — тем же, которым его узнаёт гард
+# замысла. Дерево, признака не объявившее, этого гарда не получает: судить ему нечем.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: нет `jq`, нет записи хода, нет признака дерева, повторный заход, любая
+# своя ошибка — ход РАЗРЕШАЕТСЯ (exit 0). Сломанный гард не имеет права заклинить работу.
+
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/utf8.sh" 2>/dev/null || true
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/hook-input.sh" 2>/dev/null || true
+
+rt_hook_read
+input="$RT_HOOK_INPUT"
+[ -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
+
+rt_hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Профиль дерева: сперва умолчание пакета, поверх него — надстройка проекта, если она есть.
+for profile in "$rt_hooks_dir/../rt-kit/defaults/project.sh" "$rt_hooks_dir/../defaults/project.sh" \
+    "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/project.sh"; do
+    # shellcheck disable=SC1090
+    [ -f "$profile" ] && . "$profile" 2>/dev/null
+done
+
+# shellcheck disable=SC1090
+[ -f "$rt_hooks_dir/profile-check.sh" ] && . "$rt_hooks_dir/profile-check.sh"
+command -v rt_needs >/dev/null 2>&1 || rt_needs() { command -v "$1" >/dev/null 2>&1; }
+rt_needs rt_is_app_code work-start-guard || exit 0
+
+# Ход — это всё, что записано после последнего настоящего ввода владельца. Ответ инструмента
+# приходит той же ролью, поэтому строки с `tool_result` вводом не считаются.
+#
+# Хвост в 400 строк: запись хода растёт всю сессию, а судится только последний ход.
+asked="$(tail -n 400 "$transcript" 2>/dev/null | jq -s -r '
+    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].message.content
+         | if type == "string" then .
+           elif type == "array" then (map(if type == "object" then (.text // "") else tostring end) | join("\n"))
+           else "" end)
+      end
+' 2>/dev/null)"
+
+# Ввода в записи нет вовсе — судить нечего: ход разрешается.
+[ -z "$asked" ] && exit 0
+
+# Правленные за ход файлы: инструменты правки называют путь полем, а команда оболочки — своим
+# разбором, и его здесь нет намеренно. Гард судит явную правку файла: команда, пишущая в код
+# мимо инструмента правки, остаётся его известной границей.
+edited="$(tail -n 400 "$transcript" 2>/dev/null | jq -s -r '
+    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)
+    | [.[] | select(.type == "assistant") | (.message.content // [])[]
+        | select(.type == "tool_use")
+        | select(.name == "Edit" or .name == "Write" or .name == "MultiEdit" or .name == "NotebookEdit")
+        | (.input.file_path // .input.notebook_path // empty)]
+    | unique | .[]
+' 2>/dev/null)"
+
+[ -z "$edited" ] && exit 0
+
+touched=""
+while IFS= read -r path; do
+    [ -z "$path" ] && continue
+    if rt_is_app_code "$path" 2>/dev/null; then
+        touched="$path"
+        break
+    fi
+done <<EOF
+$edited
+EOF
+
+# Код приложения за ход не правился: гард молчит. Разбор, тексты и обвязка идут своим ходом —
+# требовать слова владельца на них значило бы запретить разведку до просьбы.
+[ -z "$touched" ] && exit 0
+
+# Просьбой не бывает ни при каком прочтении: пустая реплика, одно слово, путь к файлу. Судится
+# первая непустая строка ввода: развёрнутая просьба своей первой строкой уже просьба, а путь,
+# присланный один, ею не станет и дальше.
+first="$(printf '%s' "$asked" | tr -d '\r' | sed -n '/[^[:space:]]/{p;q;}')"
+words="$(printf '%s' "$asked" | tr -s '[:space:]' '\n' | grep -c '[^[:space:]]' 2>/dev/null || echo 0)"
+
+case "$first" in
+    # Служебная отметка о прерывании: своей просьбы в ней нет.
+    '[Request interrupted'*) kind="прерывание" ;;
+    *)
+        if [ "$words" -le 1 ] 2>/dev/null; then
+            case "$first" in
+                */*) kind="путь к файлу" ;;
+                *) kind="одно слово" ;;
+            esac
+        else
+            kind=""
+        fi
+        ;;
+esac
+
+# Просьба в ходе есть: работа заказана, и гард отпускает.
+[ -z "$kind" ] && exit 0
+
+reason="BLOCKED by work-start-guard: за ход правился код приложения — «${touched}», — а последняя реплика владельца просьбой не была: ${kind}.
+
+Заход работу не начинает сам. Передача прошлого захода, состояние задачи из хука запуска и назначенный эпик говорят, что делать, если работать, и молчат о том, работать ли. Строка с адресом называет файл, а не действие: прочитанная как поручение, она даёт заходу задание, которого владелец не давал.
+
+Ход отсюда один: назови владельцу состояние работы и спроси, продолжать ли, — и дождись ответа. Сделанное этим ходом не откатывается само: скажи, что уже правлено.
+
+Гард судит один ход: следующий заход не отбивается."
+
+# Общий хвост отказа: два законных хода. Файл может быть не разложен — тогда хвоста нет,
+# а причина отказа остаётся прежней.
+# shellcheck disable=SC1090
+[ -f "$rt_hooks_dir/deny-tail.sh" ] && . "$rt_hooks_dir/deny-tail.sh" 2>/dev/null
+command -v rt_deny_tail >/dev/null 2>&1 || rt_deny_tail() { :; }
+deny_tail_text="$(rt_deny_tail "")"
+[ -n "$deny_tail_text" ] && reason="${reason}
+
+${deny_tail_text}"
+
+jq -n --arg r "$reason" '{decision:"block",reason:$r}' 2>/dev/null \
+    || printf '{"decision":"block","reason":"work-start-guard: код правился, а просьбы владельца в этом ходе не было."}\n'
+
+exit 0

package/assets/hooks/write-targets.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Цели записи, названные командой оболочки прямо: перенаправление, `tee`, правка на месте,
+# копирование поверх. Печатает по одной в строке.
+#
+# Строки `# rt-hook:` здесь нет намеренно: это помощник, а не хук. Он ничего не решает сам и
+# зовётся оттуда, где судят правку файла, — гардом места правки и гардом экзамена. Общий он
+# потому, что признак записи у обоих один и тот же: разойдясь, две копии пропустили бы разные
+# формы записи, и заметить это было бы нечем.
+#
+# Общий признак записи здесь не берётся намеренно — он широк, в нём и имя интерпретатора, и
+# запуск разложенной проверки читался бы как правка её самой. Снятие копии сюда тоже не входит:
+# снятый файл раскладка кладёт заново, и так чинят копию, которую переписал форматтер.
+
+rt_write_targets() {
+    tr "\"'\`" '   ' \
+        | sed -E 's/>>?/\n>/g' \
+        | sed -nE '
+            s/^>[[:space:]]*([^[:space:]|&;]+).*/\1/p
+            s/(^|.*[[:space:]])tee[[:space:]]+(-a[[:space:]]+)?([^[:space:]|&;]+).*/\3/p
+            s/(^|.*[[:space:]])sed[[:space:]]+-i[[:space:]]+([^[:space:]]+[[:space:]]+)*([^[:space:]|&;]+)$/\3/p
+            s/(^|.*[[:space:]])(cp|mv|install)[[:space:]]+([^[:space:]]+[[:space:]]+)+([^[:space:]|&;]+).*/\4/p
+        ' \
+        | sort -u
+}

package/assets/laws/verifiability.md

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

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

@@ -67,7 +67,9 @@ description: Паттерн правила browser-verification. Брать, к
 - Между кликами обязателен `await`: синхронный цикл «кликнул — прочитал DOM» читает состояние
   до перерисовки и возвращает устаревшие значения.
 - `select_browser` протухает через 300 секунд. На длинной проверке это срабатывает посреди
-  работы — это не сбой стенда, повторить вызов и продолжить. Закреплённый профиль — тот, что записан в дереве, идентификатор `062b17db-ae82-4264-927c-e9904d0dd5be`.
+  работы — это не сбой стенда, повторить вызов и продолжить. Закреплённый профиль называет само дерево — переменной окружения либо своим файлом рядом с
+  настройками раскладки; спрашивается он у помощника, а не помнится: идентификатор локален для
+  машины и в пакет не едет вовсе.
 
 ## Поведение роутера воспроизводится нажатиями
 

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

@@ -133,8 +133,11 @@ pnpm install --frozen-lockfile         # из ../<префикс>-base: node_mod
   коммит — проверяют сборкой, а не тем, что он в главной ветке.
 - Стенд второго дерева поднимают на своих портах: {{sitePort}}, {{adminPort}} и {{apiPort}} заняты владельцем, а {{ssrPort}}
   занимать нельзя — стенд разработчика ходит по имени `ssr:{{ssrPort}}`.
-- Оба стенда держат поднятыми одновременно: если сравнивать по памяти между двумя запусками,
-  заметишь только то, что успел запомнить.
+- Оба стенда держат поднятыми одновременно — ровно до конца сравнения: если сравнивать по памяти
+  между двумя запусками, заметишь только то, что успел запомнить. Со сравнением стенд второго
+  дерева гасится тем же ходом, а не оставляется до конца захода: оставленные стенды копятся
+  заходами и держат соединения к хранилищу, и правило говорит об этом ловушкой. Снятие отбито —
+  стенд называется владельцу в конце захода поимённо, с портом.
 
 ## Состояние портов снимается до первой сборки захода
 
@@ -160,6 +163,11 @@ done
   это по её длительности.
 - Свой дев-сервер не поднимать: сайт на {{sitePort}}, админка на {{adminPort}}, API на {{apiPort}} уже подняты
   владельцем, и второй экземпляр отбивается гардом.
+- **Дев-сервер владельца — место, где смотрят, а не место, где проверяют.** Вывод о том, что
+  экран верен, делается на прод-сборке за настоящим прокси: разметка от сервера, локали, кэш,
+  перенаправления и заголовки на дев-сервере либо другие, либо отсутствуют вовсе. Взгляд на
+  поднятый дев-сервер годится, чтобы понять, что происходит на незнакомом экране, и не годится
+  подтверждением: подтверждение — замер на стенде из прод-сборки.
 - **Общая сборка глушит все три дев-сервера владельца, а не только API.** После
   `nx run-many -t build` ложатся и сайт на {{sitePort}}, и админка на {{adminPort}}. Собирать надо то, что
   проверяешь (`npx nx build site`), а не всё дерево. Если серверы легли, поднять их обратно

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

@@ -48,7 +48,7 @@ description: Паттерн правила doc-style. Брать при напи
 
 «Не планируется», «не будет», «отдельная фича по запросу» — это намерение владельца, а не
 свойство системы. Что не сделано — да, почему не сделано — да, что не будет сделано никогда —
-нет. Вместо приговора — открытый вопрос `Q-N` с тем, что решение изменит.
+нет. Вместо приговора — открытый вопрос `Q-<буква закона>-<номер>` с тем, что решение изменит.
 
 Ошибка беззвучная: сверять утверждение о будущем не с чем, оно проходит любую проверку. Так в
 первый живой спек попало «онлайн-оплаты нет и не планируется», хотя оплата в планах.
@@ -73,12 +73,32 @@ description: Паттерн правила doc-style. Брать при напи
 фразе, которую читают, и не ловится в файле на восемьсот строк: оборот всплывает по всему
 тексту, и глазами он не считается.
 
+Берётся чужой оборот оттуда, что писавший только что читал, и сильнее всего это бьёт при письме
+в том же роде: ни одного слова вне словаря в такой фразе нет, каждое проходит вычитку по
+отдельности, а непонятной оказывается фраза целиком. Вводный абзац поэтому пишется последним —
+когда источник уже выветрился.
+
 Вторая половина проверки — счёт, и там, где дерево разложило проверку слога
 `checks/check-prose-style.mjs`, набор оборотов накоплен в ней самой: каждый признак назван
 вместе с заменой, а находка печатается файлом и строкой. Оборот, найденный вычиткой,
 дописывается в набор тем же ходом — иначе следующий пишущий начинает с пустого места и
 собирает его заново из своей памяти.
 
+Читается не только слово, но и то, одно ли у фразы прочтение. Три причины нечитаемости приходят
+по очереди, и правка одной заводит следующую — статью закона переписывали трижды, и каждый раз
+владелец не понимал её по новой причине:
+
+```text
+✗ не различать их нельзя                        — двойное отрицание читается наоборот сказанному
+✗ у каждого видно, откуда он взялся             — местоимение без хозяина, а «взялся» не называет действия
+✗ либо снимается ролью, либо остаётся навсегда  — два исхода через «или» без правила, по которому наступает тот или другой
+
+✓ выданное лично снимается только лично: роль этого не трогает
+```
+
+Довод «без такого устройства было бы так» в текст не идёт вовсе: он спорит с тем, чего нет, и
+читается как «это к чему?».
+
 Чего не видит ни слух, ни она: повтора законного оборота. Каждое его появление законно
 поодиночке, а стоящий в тексте десятками он уже не приём, а тик — читатель перестаёт замечать
 его вместе со смыслом. Считается это грепом по тексту, и число само по себе отказом не бывает:

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

@@ -115,7 +115,7 @@ $GH api graphql -f query='mutation { deleteIssue(input: {issueId: "<node-id>"})
 составная команда отклоняется целиком — ветки в ней ещё нет:
 
 ```bash
-✗ git checkout -b <КЛЮЧ>-85-guest-token && git commit -m 'feat(admin): …'
+✗ git checkout -b <КЛЮЧ>-85-guest-token && git commit -m 'feat(<область>): …'
 ✓ git checkout -b <КЛЮЧ>-85-guest-token
 ✓ git commit -F -
 ```
@@ -166,11 +166,25 @@ GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<номер>+<бот>@users.n
 конце заголовка не принимается, длина — до 150 знаков.
 
 ```
-feat(site): availability calendar with season prices
-fix(api): reject overlapping booking dates
+feat(<область>): availability calendar with season prices
+fix(<область>): reject overlapping booking dates
 chore(deploy): docker-compose for vps
 ```
 
+## Файлы своей работы называются поимённо
+
+Рабочее дерево одно, а работ в нём бывает несколько: чужая незакоммиченная папка, оставленный
+черновик, правка соседнего захода. Каталог, добавленный целиком, уносит их с собой, и в главную
+ветку уезжает то, о чём эта работа не просила.
+
+```bash
+git add docs/tasks/<КЛЮЧ>-<номер>-<slug>/plan.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/progress.md
+git diff --cached --name-only     # что действительно встало в индекс
+```
+
+Проверки индекса после добавления мало: однажды добавленный чужой файл становится
+отслеживаемым и дальше едет молча — следующий `git add` его уже не спрашивает.
+
 ## Документ едет тем же коммитом
 
 `docs-guard` требует пару и называет её сам. Обход — строка в теле, причина обязательна:
@@ -182,6 +196,7 @@ Docs-skip: правка только в тестах хука, зеркала у
 ## Частые промахи
 
 - `gh` в оболочке пользователя подменён — звать `/opt/homebrew/bin/gh` напрямую.
+- Каталог добавлен целиком при чужом незакоммиченном рядом: чужая папка задачи уехала в главную ветку и стала отслеживаемой.
 - `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
   команда обрывается на первом промахе целиком, а не пропускает его. Следующий
   `git commit --amend` при этом уносит в коммит всё, что осталось в индексе, — так в коммит

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

@@ -96,6 +96,14 @@ docker builder prune --force --filter until=24h       # вчерашний кэ
 Освобождают отбором, а не общей чисткой: у сценария чистки образов сперва спрашивают, что он
 снял бы, и только потом дают снимать.
 
+**Снятие образов отбивает не гейт, а режим захода.** В автоматическом режиме команда с
+необратимым удалением — снятие образа, чистка слоёв — отклоняется независимо от разрешений, и
+разрешающее правило на ту же команду отказа не снимает. Повторный вызов отбивается так же: отказ
+не зависит от того, как команда набрана, поэтому переформулировка тут не путь. Ходов отсюда два —
+освободить место тем, что удаления не требует, либо назвать это владельцу: режим переключает он,
+и снимает образы тоже он. Названное в конце захода стоит целого прогона: конвейер всё это время
+стоит красным по нехватке места.
+
 ## Демон поднимается своим CLI
 
 Открытие приложения виртуальную машину не поднимает: приложение считается запущенным, а демон

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

@@ -0,0 +1,87 @@
+---
+name: git-workflow-freshness
+kind: pattern
+rule: git-workflow
+description: Паттерн правила git-workflow. Брать перед пушем, при взятии задачи и после каждого известного слияния: чтение всех своих открытых заявок разом, отделение отставания от спора в файлах, сверка локальной вершины с хостингом.
+---
+
+# Свежесть открытых заявок
+
+Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`. Разбор одного конфликта — паттерн `git-workflow-merge`,
+череда веток из одного основания — `git-workflow-stack`.
+
+## Когда брать
+
+Три места, и в каждом чтение обязательно:
+
+- перед пушем — вершина главной могла уйти, пока шла работа;
+- при взятии новой задачи — прежние заявки остались открытыми и о себе не напомнят;
+- после каждого слияния, о котором стало известно, — оно отставило все остальные разом.
+
+## Что читается
+
+Одной командой по всем своим открытым заявкам, а не по той, чья ветка сейчас взята:
+
+```bash
+/opt/homebrew/bin/gh pr list --author '<машинная запись>' --state open \
+    --json number,headRefName,isDraft,mergeable,mergeStateStatus,statusCheckRollup
+```
+
+| Поле                 | Что говорит                                                                       |
+| -------------------- | --------------------------------------------------------------------------------- |
+| `mergeable`          | `MERGEABLE` — кнопку нажать можно; `CONFLICTING` — нельзя; `UNKNOWN` — ещё не посчитано |
+| `mergeStateStatus`   | `BEHIND` — отстала от главной; `DIRTY` — спор в файлах; `BLOCKED` — ждёт разбора  |
+| `isDraft`            | черновик: кнопка слияния заблокирована хостингом при любом цвете прогона          |
+| `statusCheckRollup`  | прогон на вершине: пустой список — прогона нет вовсе, а не «зелено»               |
+
+`UNKNOWN` означает «ещё не посчитано» и читается как «спросить снова через несколько секунд»,
+а не как «конфликтов нет».
+
+## Спор в файлах отделяется от отставания
+
+Метка хостинга говорит одно — «нажать нельзя». Что именно чинить, отвечает слияние деревьев,
+и отвечает без сети:
+
+```bash
+git fetch origin
+git merge-tree "$(git merge-base origin/main <ветка>)" origin/main <ветка> | grep -c '^<<<<<<<'
+```
+
+Ноль — ветка просто отстала, и лечится это вливанием главной. Больше нуля — спор в файлах, и
+каждый разбирается по роду файла: паттерн `git-workflow-merge`.
+
+## Что делается с найденным
+
+| Найдено                                | Что делается                                                       |
+| -------------------------------------- | ------------------------------------------------------------------ |
+| отстала, спора нет                     | главная вливается в ветку и отправляется тем же ходом              |
+| спор в файлах                          | разбор по роду файла, затем отправка                               |
+| прогона на вершине нет                 | вершина перезапускается или дожидается — цвета нет ни у той, ни у другой |
+| черновик при зелёном прогоне           | черновик снимается — у него кнопка слияния заблокирована           |
+| заявка открыта человеком, а не машиной | ревьювера ей уже не поставить: заводится заново машинной записью   |
+
+Внутри одной ветки порядок один: влить главную → прогнать набор гейта → отправить → перечитать
+состояние у хостинга. Перечитывание — часть работы, а не отчёт о ней.
+
+## Локальная вершина сверяется с той, что на хостинге
+
+Догнанная в рабочем дереве и не отправленная ветка работой не считается: человек видит прежнее
+состояние.
+
+```bash
+git rev-parse HEAD
+/opt/homebrew/bin/gh pr view <номер> --json headRefOid --jq .headRefOid
+```
+
+Разошлись — отправка не сделана, и это первое, что чинится.
+
+## Частые промахи
+
+- Состояние заявки прочитано по памяти прошлого хода: между ходами человек влил соседнюю работу.
+- `UNKNOWN` прочитан как «конфликтов нет» — хостинг ещё считал.
+- Читалась заявка текущей ветки, а брошенные остались отставшими: спрашиваются все свои открытые.
+- Главная влита в рабочем дереве и не отправлена: снаружи это «не сделано ничего».
+- Отставание лечили разбором конфликта: спора в файлах не было вовсе, хватило бы вливания.
+- Спор разрешили выбором стороны целиком: род файла решает приём, и стороны у него разные.
+- Круг догоняния начат по окрику человека, а не сам: к этой минуте отстали уже все заявки.

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

@@ -10,6 +10,10 @@ description: Паттерн правила git-workflow. Брать, когда
 Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
 `docs/constitution/delivery.md`.
 
+**Вызовы здесь даны клиентом GitHub.** Дерево на другом хостинге читает их как форму, а команду
+берёт у своего клиента: имена полей и подкоманд у клиентов разные, а спрашиваемое — одно.
+Соответствие называет редакция правила поставки, разложенная в этом дереве.
+
 ## Когда брать
 
 - PR отмечен конфликтующим, и его надо вернуть к сливаемому состоянию.
@@ -115,13 +119,32 @@ PR описывал дерево на день, когда его написал
 /opt/homebrew/bin/gh api -X PATCH repos/<владелец>/<репозиторий>/pulls/<номер> -f body="$(cat тело.md)"
 ```
 
+## Зелёный прогон стареет вместе с главной веткой
+
+Прогон говорит про то основание, на котором шёл. Пока он идёт, а заявка ждёт разбора, главная
+ветка живёт своей жизнью, и локальная ссылка об этом молчит: она описывает день, когда её
+подтянули. Перед тем как назвать заявку готовой к слиянию, отставание спрашивается у хранилища:
+
+```bash
+/opt/homebrew/bin/gh api repos/<владелец>/<репозиторий>/compare/<главная>...<ветка> --jq .behind_by
+```
+
+Ноль — заявка готова. Больше нуля — главная вливается, набор проверок пересматривается по тому,
+что ветка везёт теперь, и прогон идёт заново: зелёные задания прошлого прогона после вливания не
+значат ничего.
+
 ## Частые промахи
 
 - «Сохранить обе стороны» применено ко всем файлам одинаково: в спеке это верно, в коде и в
   списке работ — нет.
+- Команда мержа взята без переменных подписи: коммит слияния подписан человеком, и отбивает его
+  набор пуша — на том шаге, где все проверки уже зелёные. Чинится это переписыванием ветки, а не
+  правкой одного коммита: за слиянием обычно уже лежат разрешения конфликтов.
 - Сторона ветки перенесена без сверки с очередью работ: одна работа стала двумя записями.
 - После разрешения прогнана сборка, а проверки текстов — нет: конфликта в них сборке не видно.
 - Тело PR оставлено прежним: ревьювер читает утверждение о дереве, которого больше нет.
+- Заявка названа готовой по зелёному прогону: задания шли от основания, которого в главной ветке
+  уже нет.
 - Раздел, снятый главной веткой, вернулся «сохранением обеих сторон»: в спеке два экземпляра
   одного абзаца, и снятый читается как действующий.
 - Черри-пик взят без переменной коммиттера: автор у коммита прежний, коммиттер — человек, и отправку отбивает набор проверок.

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

@@ -177,6 +177,12 @@ $GH api "repos/$REPO/pulls/321" \
 назначить автора ревьювером нельзя, а отказа на такой запрос не приходит. Владельцу называют
 то, что прочитали, а не то, что заказывали.
 
+Прочитанное расхождение имеет назначенное действие, а не остаётся наблюдением: автора у заявки
+не сменить, правкой это не чинится. Заявка закрывается и открывается заново токеном машинной
+записи — с переносом тела, меток, ревьювера и исполнителя. Номер при этом сменится, и строки,
+которые ссылались на прежний, переписываются тем же ходом. Развилка, вынесенная тут владельцу,
+означает, что порядок поставки прочитан и не исполнен: ход отсюда один.
+
 Учётная запись, из-под которой пришлось пушить, в этот вызов не переносится: пуш и авторство
 PR выбираются отдельно, и `GH_TOKEN` для публикации — всегда токен бота.
 

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

@@ -41,6 +41,24 @@ docker inspect <контейнер> --format '{{.Config.Image}}'
 `integrations` из логов исчезает, хотя `API is running` остаётся на месте. После перезапуска —
 тот же `inspect` и наличие ожидаемых строк в логе.
 
+## Откат: тот же вызов с прежним sha
+
+Откат — не отдельный механизм, а тот же подъём по sha, только взятому на шаг назад. Прежний sha
+берётся у реестра, где чистка оставляет три последних, — глубже отката нет:
+
+```bash
+docker image ls '<реестр>/<образ>' --format '{{.Tag}}\t{{.CreatedAt}}' | sort -k2 -r | head -3
+IMAGE_TAG='<прежний sha>' docker compose -f docker-compose.prod.yml --env-file .env.prod up -d --no-build
+```
+
+Откат возвращает прежний образ, но не прежнюю схему хранилища: миграция, уехавшая с новой
+версией, остаётся применённой, и прежний образ работает с изменённой схемой. Правка схемы
+поэтому и делится на совместимую и несовместимую — паттерн миграции.
+
+Откаченный прод сходится с главной веткой не сразу: главная везёт правку, которой на проде уже
+нет. Строкой очереди работ это не видно вовсе, и владельцу называется словами, вместе с sha, на
+который откатились.
+
 ## Частые промахи
 
 - Вывод «прод жив, значит выкатилось» — код ответа подмену образа не показывает.

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

@@ -11,6 +11,10 @@ description: Паттерн правила git-workflow. Брать, когда
 `docs/constitution/delivery.md`. Разбор одного конфликта — паттерн `git-workflow-merge`,
 открытие одной заявки — `git-workflow-pr`.
 
+**Вызовы здесь даны клиентом GitHub.** Дерево на другом хостинге читает их как форму, а команду
+берёт у своего клиента: имена полей и подкоманд у клиентов разные, а спрашиваемое — одно.
+Соответствие называет редакция правила поставки, разложенная в этом дереве.
+
 ## Когда брать
 
 - Из одного основания заведено больше двух веток, и все ждут слияния.
@@ -48,6 +52,13 @@ gh pr create --base <предыдущая ветка> --title '[<КЛЮЧ>-<но
 Порядок вливания стоит в теле каждой заявки строкой «стоит на #<номер>, вливать после него»:
 владелец вливает по списку, а родство веток по списку не видно.
 
+**Конвейер дерева проверяется на то, слушает ли он заявку с таким основанием.** Событие заявки
+хостинг шлёт с фильтром по базе, и дерево, оставившее в фильтре одну главную ветку, всей череде
+прогонов не даёт вовсе: заявка стоит зелёно-пустой, а вернуть событие нечем — ни новый коммит,
+ни перезакрытие заявки базы не меняют. Спрашивается это до того, как череду заводить: у
+настройки конвейера, а не у страницы заявки, где отсутствие прогона выглядит так же, как его
+ожидание.
+
 ```bash
 # порядок череды целиком — снизу вверх
 gh pr list --state open --json number,headRefName,baseRefName \
@@ -141,6 +152,25 @@ done | sort | uniq -c | sort -rn | head
 конфликт там, где подряд его бы не было. Порядок называется владельцу в теле заявки — кнопки
 нажимает он, а о родстве веток не знает.
 
+## Волна веток проверяется пробным слиянием
+
+Ветка, лежащая невлитой рядом с соседками, зелена сама по себе: линт, тесты, сборки и сверки
+она проходит одна. Сталкивается она с ними тем, чего на отдельной ветке не видит ни одна
+проверка — тот же следующий свободный номер сценария, тот же заведённый новым файл, та же
+правленная строка отметки. После слияния первые два чинятся уже в главной и стоят отдельной
+работы.
+
+```bash
+git fetch origin
+git checkout -b probe-merge origin/main
+for b in <ветка-1> <ветка-2> <ветка-3>; do git merge --no-edit "origin/$b" || break; done
+npm run check:all
+git checkout - && git branch -D probe-merge
+```
+
+Ветка пробы удаляется, а находки и порядок слияния записываются туда, где живёт замысел линии
+работ: пробное слияние отвечает на «что столкнётся», а не заменяет собой отдачу.
+
 ## Частые промахи
 
 - Открыты все заявки разом, потому что ветки были готовы. Готовность ветки признаком того, что

package/assets/patterns/lib-layers-move.md

@@ -77,6 +77,10 @@ grep -rn "@<область>/<семья>/<домен>" libs/ apps/ | sed 's/:.*/
     npx nx run-many -t lint --projects=<список по изменённым файлам>
     ```
 
+    Этот прогон — быстрый, по горячим следам переноса, и набором перед пушем он не бывает:
+    набор, собранный по изменённым файлам, пропускает то, до чего правка дошла связями. Перед
+    пушем идёт тот же набор, что гоняет конвейер, и теми же командами.
+
 ## Проверить
 
 ```bash