@rt-tools/agent-kit 0.8.1 → 0.8.3

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

@@ -2,7 +2,7 @@
 name: git-workflow-commit
 kind: pattern
 rule: git-workflow
-description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит, пуш и создание PR — готовая команда заведения задачи со всеми четырьмя шагами, перевод задачи в колонку работы и в колонку разбора, слияние двух задач в одну, сверка очереди работ, работа от учётной записи бота, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки PR, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит, пуш и создание PR — готовая команда заведения задачи со всеми четырьмя шагами, перевод задачи в колонку работы и в колонку разбора, слияние двух задач в одну, сверка очереди работ, работа от учётной записи бота, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки PR, образец тела PR с разделом об оставшемся шаге, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
 ---
 
 # Ветка, коммит и PR
@@ -46,6 +46,15 @@ gh project item-add <номер борды> --owner <владелец> --url <а
 
 Последний шаг и есть тот, который забывается: без него задача заведена, но её нет в очереди.
 
+Заведение кончается не выводом команды, а ответом очереди работ. Команда спрашивает её сама и
+печатает прочитанное — присутствие на борде, колонку, исполнителя; отсутствие кончает её
+ненулевым кодом. В комментарий, в тело PR и в замысел идёт этот ответ, а не напечатанный
+номер: номер говорит «вызов прошёл», а не «задача видна тому, кто по ней работает».
+
+Заведения, идущие подряд, проверяются не по последнему, а сверкой очереди целиком: промах у них
+общий, и по одной задаче он не виден. Шестнадцать задач подряд напечатали номер, и ни одна не
+попала в очередь так, чтобы её увидел владелец.
+
 Название тикета говорит, что не так, а не что сделать: PR потом переводит его в сделанное.
 Номер в заголовок руками не пишется — он известен только после создания, и команда дописывает
 его сама.
@@ -182,6 +191,31 @@ PR      [<КЛЮЧ>-212] Виджет переписки зовёт кит ег
 коммита, и там его сверяет `commitlint`. В списке PR он занимает место, ничего не добавляя:
 род правки и область уже видны метками.
 
+## Не готовое к слиянию открывается черновиком
+
+Правка кода отдаётся человеку открытым PR: запушенная ветка ему не показывается нигде. Открытый
+PR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
+черновиком — кнопку слияния у черновика хостинг блокирует сам:
+
+```bash
+GH_TOKEN="$TOKEN" gh pr create --draft --title '[<КЛЮЧ>-86] …' --body-file тело.md
+```
+
+Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
+задаётся в самом PR, а не остаётся в голове исполнителя: человек читает PR, а не переписку
+захода.
+
+Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
+решение готово:
+
+```bash
+GH_TOKEN="$TOKEN" gh pr ready 86
+```
+
+До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
+черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
+ждёт разбора ровно так же, как не снятый.
+
 ## PR прикрепляется к задаче
 
 Тело начинается со строки связи — по ней на борде заполняется поле «Linked pull requests».
@@ -227,9 +261,49 @@ $GH api -X POST "repos/$REPO/pulls/205/requested_reviewers" -f 'reviewers[]=<в
 $GH api -X PATCH "repos/$REPO/pulls/205" -f body="$(cat тело.md)"
 ```
 
-Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: отчёт
+Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: PR
 утверждает про дерево, а дерево с тех пор изменилось.
 
+## Образец тела PR
+
+Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
+оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
+заголовок читаются одинаково, а значат разное.
+
+```markdown
+Closes #86
+
+## Что сделано
+
+- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
+
+## Чем подтверждено
+
+- <проверка>: <её вывод одной строкой>
+- Не гонялось: <что в набор не вошло и почему>
+
+## Оставшийся шаг
+
+После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
+вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
+```
+
+Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
+— в тот ход, которым папка разбирается и снимается черновик:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
+```
+
+Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
+сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
+не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
+
+Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
+заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
+
 ## Состояние PR читается, а не додумывается
 
 Вызовы, которыми ставятся ревьювер, метки и исполнитель, отвечают нулевым кодом и тогда, когда
@@ -270,6 +344,10 @@ npm run task:move -- 86 in-review
 гоняет ничего. Линтеры, юниты и сценарии хуков снимает гейт пуша — ниже то, чего он не знает.
 
 1. **Главная ветка влита в эту ветку** — `git fetch origin && git merge origin/main`.
+   Свежесть основания между ветками одного захода не наследуется: вторая и третья ветка
+   отводятся после своего `fetch`, а не от ссылки, подтянутой под первую. Пока идёт работа,
+   главная уходит вперёд — чаще всего собственным PR того же исполнителя, влитым час
+   назад.
    Всё, что проверяется ниже, проверяется от этого основания: PR с разошедшейся ветки
    показывает ревьюверу правку вперемешку с чужой. Порядок и разбор конфликта — паттерн
    `git-workflow-merge`.
@@ -290,7 +368,10 @@ npm run task:move -- 86 in-review
    `browser-verification-measure`.
 9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** — паттерн
    `seo-verify`.
-10. **Тело PR начинается строкой `Closes #<номер>`**, а метки, ревьювер и исполнитель стоят.
+10. **Тело PR собрано по образцу** — начинается строкой `Closes #<номер>`, несёт разделы «Что
+    сделано», «Чем подтверждено» и «Оставшийся шаг», а метки, ревьювер и исполнитель стоят.
+    Раздел оставшегося шага к этому моменту говорит, что шагов не осталось: черновик снимается
+    после разбора папки, а не до него.
 11. **Заголовок PR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что сделано>`,
     тем же номером, что стоит у задачи и в имени ветки. Инфинитив из задачи в него не
     переносится, тип и область коммита — тоже.
@@ -305,7 +386,12 @@ npm run task:move -- 86 in-review
 15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
     теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
     снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
-    отчёт.
+    PR.
+
+Список этот — про снятие черновика, а не про его открытие. Черновиком PR открывается раньше:
+пока работа идёт, человеку показывают то, что уже есть, вместе с тем, чего ещё нет. Пункты 1–15
+проходятся перед `gh pr ready`, и невыполненный пункт означает, что черновик не снимается, — а
+не то, что PR не открывается.
 
 Сразу после публикации задача переставляется в разбор — `npm run task:move -- <номер>
 in-review`, — и `npm run check:board` прогоняется ещё раз: до открытия PR колонку он не судит,

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

@@ -2,7 +2,7 @@
 name: git-workflow-commit
 kind: pattern
 rule: git-workflow
-description: Паттерн правила git-workflow для дерева на GitLab. Брать на заведение задачи, ветки, коммит, пуш и создание MR — заведение задачи со всеми шагами, перевод по спискам доски, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки MR, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
+description: Паттерн правила git-workflow для дерева на GitLab. Брать на заведение задачи, ветки, коммит, пуш и создание MR — заведение задачи со всеми шагами, перевод по спискам доски, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки MR, образец описания MR с разделом об оставшемся шаге, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
 ---
 
 # Ветка, коммит и MR
@@ -46,6 +46,14 @@ glab issue update <номер> --title '[<КЛЮЧ>-<номер>] …'   # но
 Метка списка ставится при заведении, а не после: issue без неё лежит вне доски, и увидеть её
 можно только поиском по проекту.
 
+Заведение кончается не выводом команды, а ответом очереди работ. Команда спрашивает её сама и
+печатает прочитанное — присутствие на доске, список, исполнителя; отсутствие кончает её ненулевым
+кодом. В комментарий, в тело PR и в замысел идёт этот ответ, а не напечатанный номер: номер
+говорит «вызов прошёл», а не «задача видна тому, кто по ней работает».
+
+Заведения, идущие подряд, проверяются не по последнему, а сверкой очереди целиком: промах у них
+общий, и по одной задаче он не виден.
+
 Чем сверить, что очередь работ в порядке:
 
 ```bash
@@ -167,6 +175,34 @@ MR      [<КЛЮЧ>-86] Письмо владельцу с незаполнен
 коммита, и там его сверяет `commitlint`. В списке MR он занимает место, ничего не добавляя:
 род правки и область уже видны метками.
 
+## Не готовое к слиянию открывается черновиком
+
+Правка кода отдаётся человеку открытым MR: запушенная ветка ему не показывается нигде. Открытый
+MR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
+черновиком — кнопку слияния у черновика хостинг блокирует сам:
+
+```bash
+GITLAB_TOKEN="$TOKEN" glab mr create --draft --title '[<КЛЮЧ>-86] …' --description "$(cat тело.md)"
+```
+
+Признак черновика здесь — приставка `Draft:` в заголовке MR, и правится он вместе с ним:
+переписав заголовок вручную, черновик снимают, не заметив этого.
+
+Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
+задаётся в самом MR, а не остаётся в голове исполнителя: человек читает MR, а не переписку
+захода.
+
+Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
+решение готово:
+
+```bash
+GITLAB_TOKEN="$TOKEN" glab mr update 86 --ready
+```
+
+До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
+черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
+ждёт разбора ровно так же, как не снятый.
+
 ## MR прикрепляется к задаче
 
 Описание начинается со строки связи. Ревьювер, исполнитель и метки задаются той же командой, и
@@ -203,8 +239,48 @@ glab mr update 205 --description "$(cat тело.md)"
 ```
 
 Правка описания переписывает его целиком, поэтому строка `Closes #<номер>` пишется заново
-вместе с остальным текстом. Тело перечитывается всякий раз, когда в ветку что-то влилось после
-публикации: отчёт утверждает про дерево, а дерево с тех пор изменилось.
+вместе с остальным текстом. Описание перечитывается всякий раз, когда в ветку что-то влилось
+после публикации: MR утверждает про дерево, а дерево с тех пор изменилось.
+
+## Образец описания MR
+
+Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
+оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
+заголовок читаются одинаково, а значат разное.
+
+```markdown
+Closes #86
+
+## Что сделано
+
+- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
+
+## Чем подтверждено
+
+- <проверка>: <её вывод одной строкой>
+- Не гонялось: <что в набор не вошло и почему>
+
+## Оставшийся шаг
+
+После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
+вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
+```
+
+Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное
+описание, — в тот ход, которым папка разбирается и снимается черновик:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
+```
+
+Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
+сказанное владельцу вслух живёт до следующей реплики, а описание лежит у самой кнопки. Одно
+другого не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
+
+Проверить описание машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
+заголовок. Держится образец тем, кто пишет описание, — как и слова вслух.
 
 ## Состояние MR читается, а не додумывается
 
@@ -256,7 +332,10 @@ npm run task:move -- 86 in-review
    `browser-verification-measure`.
 9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** —
    паттерн `seo-verify`.
-10. **Описание MR начинается строкой `Closes #<номер>`**, а метки, ревьювер и исполнитель стоят.
+10. **Описание MR собрано по образцу** — начинается строкой `Closes #<номер>`, несёт разделы
+    «Что сделано», «Чем подтверждено» и «Оставшийся шаг», а метки, ревьювер и исполнитель
+    стоят. Раздел оставшегося шага к этому моменту говорит, что шагов не осталось: черновик
+    снимается после разбора папки, а не до него.
 11. **Заголовок MR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что
 сделано>`, тем же номером, что стоит у задачи и в имени ветки.
 12. **Очередь работ сходится** — `npm run check:board`.
@@ -268,7 +347,7 @@ npm run task:move -- 86 in-review
 15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
     теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
     снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
-    отчёт.
+    PR.
 
 Сразу после публикации задача переставляется в разбор, и сверка очереди прогоняется ещё раз: до
 открытия MR список она не судит, а после открытия расхождение видит.

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

@@ -63,6 +63,36 @@ docker run --rm alpine:3 df -h /       # сколько осталось у са
 отвечает про ненакатываемую цепочку, гейт пуша краснеет целиком. По этим признакам чинят
 репозиторий, а причина в машине, — поэтому первое при любом из них `docker system df`.
 
+Диск хоста при этом остаётся свободным и говорит «места полно»: сквозной набор упал на
+`could not extend file … No space left on device`, когда на хосте было свободно 98 ГБ. Место
+меряется у докера, а не у машины.
+
+## Мусор снимается отбором, и чужое из него исключается по метке
+
+Тома переживают свои контейнеры и накапливаются молча: `docker ps` их не показывает, а
+`docker system df` считает одной строкой. Копятся они по-разному — контейнер без `--rm`
+оставляет том всегда, а `docker run --rm` анонимный том снимает вместе с контейнером сам, и
+докручивать к нему `-v` не надо: у `docker run` этот флаг означает монтирование и без значения
+команду ломает. Снимает тома `-v` у `docker rm`, а не у `docker run`.
+
+Признак своего — отсутствие метки состава: том, заведённый чьим-то `docker compose`, несёт
+`com.docker.compose.project` и принадлежит тому проекту, в том числе чужому.
+
+```bash
+docker volume ls -q -f dangling=true | wc -l          # сколько накопилось неиспользуемых
+for v in $(docker volume ls -q -f dangling=true); do
+    [ -z "$(docker volume inspect "$v" --format '{{index .Labels "com.docker.compose.project"}}')" ] \
+        && docker volume rm "$v"
+done
+docker builder prune --force --filter until=24h       # вчерашний кэш ничей, свежий нужен сборке
+```
+
+Порог у кэша, а не полная чистка: снятый целиком, он заставляет следующую сборку идти с нуля.
+
+Прогон конвейера, живущий на машине владельца, убирает за собой сам и делает это шагом,
+который идёт и при падении: место кончается ровно тогда, когда прогон падает, и уборка,
+пропущенная на падении, не случается в тот единственный раз, когда она была нужна.
+
 Освобождают отбором, а не общей чисткой: у сценария чистки образов сперва спрашивают, что он
 снял бы, и только потом дают снимать.
 

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

@@ -81,7 +81,7 @@ bash .claude/hooks/tests/run.sh       # если конфликт задел х
 
 ## Тело открытого PR перечитывается после мержа
 
-Отчёт описывал дерево на день, когда его написали. Мерж главной ветки меняет то, о чём он
+PR описывал дерево на день, когда его написали. Мерж главной ветки меняет то, о чём он
 утверждает: тело говорило, что оба дефекта заведены в `docs/BACKLOG.md`, а главная ветка этот
 список к тому времени разобрала. Правится тело вызовом REST — `gh pr edit` в этом репозитории
 отвечает отказом про Projects (classic) и до правки не доходит:

package/assets/patterns/spec-driven-domain.md

@@ -43,6 +43,12 @@ docs/specs/<домен>/
 
 Текст заголовка сверяется дословно. «Не применимо» — законный ответ, отсутствие раздела — нет.
 
+`## Решения` — временное место. Решение живёт в нём, пока не найден слой, которому оно
+принадлежит; найденный слой забирает его пунктом, а в спеке не остаётся ничего. Разросшийся
+раздел читается как признак незаведённого правила, а не как свойство сложного домена: делить
+такой спек по строкам бесполезно, потому что делится в нём не описание домена, а ненаписанное
+правило.
+
 Шапка несёт статус, дату ревизии, префикс сценариев, зависимости от других доменов, строку
 `**Законы:**` — законы, которые домен применяет, — и строку `**Процедуры:**` — корни либ, чьи
 процедуры домен обслуживает.
@@ -129,7 +135,7 @@ docs/specs/<домен>/
 - Пометка «Не покрыто» при существующем тесте — отказ: долг закрыли, а отметку не сняли.
 - Пометка «Не покрыто» читается дословно и с начала строки. Любое слово между ней и двоеточием
   — «Не покрыто, и прогоном не покрывается вовсе: …» — и сценарий считается непомеченным вовсе,
-  а причина, ради которой пометку и писали, до отчёта не доезжает.
+  а причина, ради которой пометку и писали, до PR не доезжает.
 - Закон, названный в тексте, но забытый в строке `**Законы:**`: по закону тогда не узнать,
   какие домены на нём стоят.
 - Правка `.proto` без спеков задетых доменов: `docs-guard` отбивает такой коммит.

package/assets/patterns/spec-driven-rule.md

@@ -123,6 +123,12 @@ description: Паттерн правила git-workflow. Брать … Не б
   правку сущности оказались привязаны к механике, которую не зовёт ни один экран.
 - Утверждение переформулировали, а строку в привязке не тронули: связь идёт по тексту, и
   проверка перестанет её находить.
+- Строка привязки дописана в конец компаньона, а не вставлена в таблицу. После таблицы там идут
+  ещё разделы — «Чем это проверяется», «Что ещё стоит знать при чтении кода», — и приписанная в
+  конец строка в таблицу не попадает вовсе: утверждение читается непривязанным, а сверка спеков
+  на это молчит, потому что ищет строку в таблице. Место строки то же, что у её утверждения в
+  правиле: порядок обеих сторон держится одинаковым, иначе утверждение и его привязка перестают
+  находиться друг по другу.
 - В `description` не сказано, когда паттерн **не** брать, — соседний паттерн того же правила
   становится неотличимым.
 - Блок готового кода принят по виду, а не сверкой с объявлением. Вызов в примере повторяет имя,