@rt-tools/agent-kit 0.8.2 → 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
@@ -191,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».
@@ -239,6 +264,46 @@ $GH api -X PATCH "repos/$REPO/pulls/205" -f body="$(cat тело.md)"
 Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: PR
 утверждает про дерево, а дерево с тех пор изменилось.
 
+## Образец тела PR
+
+Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
+оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
+заголовок читаются одинаково, а значат разное.
+
+```markdown
+Closes #86
+
+## Что сделано
+
+- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
+
+## Чем подтверждено
+
+- <проверка>: <её вывод одной строкой>
+- Не гонялось: <что в набор не вошло и почему>
+
+## Оставшийся шаг
+
+После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
+вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
+```
+
+Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
+— в тот ход, которым папка разбирается и снимается черновик:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
+```
+
+Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
+сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
+не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
+
+Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
+заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
+
 ## Состояние PR читается, а не додумывается
 
 Вызовы, которыми ставятся ревьювер, метки и исполнитель, отвечают нулевым кодом и тогда, когда
@@ -303,7 +368,10 @@ npm run task:move -- 86 in-review
    `browser-verification-measure`.
 9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** — паттерн
    `seo-verify`.
-10. **Тело PR начинается строкой `Closes #<номер>`**, а метки, ревьювер и исполнитель стоят.
+10. **Тело PR собрано по образцу** — начинается строкой `Closes #<номер>`, несёт разделы «Что
+    сделано», «Чем подтверждено» и «Оставшийся шаг», а метки, ревьювер и исполнитель стоят.
+    Раздел оставшегося шага к этому моменту говорит, что шагов не осталось: черновик снимается
+    после разбора папки, а не до него.
 11. **Заголовок PR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что сделано>`,
     тем же номером, что стоит у задачи и в имени ветки. Инфинитив из задачи в него не
     переносится, тип и область коммита — тоже.
@@ -320,6 +388,11 @@ npm run task:move -- 86 in-review
     снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
     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
@@ -175,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 прикрепляется к задаче
 
 Описание начинается со строки связи. Ревьювер, исполнитель и метки задаются той же командой, и
@@ -211,8 +239,48 @@ glab mr update 205 --description "$(cat тело.md)"
 ```
 
 Правка описания переписывает его целиком, поэтому строка `Closes #<номер>` пишется заново
-вместе с остальным текстом. Тело перечитывается всякий раз, когда в ветку что-то влилось после
-публикации: PR утверждает про дерево, а дерево с тех пор изменилось.
+вместе с остальным текстом. Описание перечитывается всякий раз, когда в ветку что-то влилось
+после публикации: MR утверждает про дерево, а дерево с тех пор изменилось.
+
+## Образец описания MR
+
+Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
+оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
+заголовок читаются одинаково, а значат разное.
+
+```markdown
+Closes #86
+
+## Что сделано
+
+- <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
+
+## Чем подтверждено
+
+- <проверка>: <её вывод одной строкой>
+- Не гонялось: <что в набор не вошло и почему>
+
+## Оставшийся шаг
+
+После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
+вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
+```
+
+Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное
+описание, — в тот ход, которым папка разбирается и снимается черновик:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
+```
+
+Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
+сказанное владельцу вслух живёт до следующей реплики, а описание лежит у самой кнопки. Одно
+другого не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
+
+Проверить описание машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
+заголовок. Держится образец тем, кто пишет описание, — как и слова вслух.
 
 ## Состояние MR читается, а не додумывается
 
@@ -264,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`.

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/task-flow-close.md

@@ -12,10 +12,91 @@ description: Паттерн правила task-flow. Брать при закр
 
 ## Когда брать
 
-- Этапы замысла закрыты, проверки зелёные, PR готовится к публикации.
+- Этапы замысла закрыты, проверки зелёные, с PR снимается черновик.
 - `npm run check:specs` перечислил договорённость в разделе «Пора вливать».
 
-## 9. Договорённость вливается в спек домена
+Само открытие PR сюда не относится: он открывается черновиком тем ходом, которым правка
+кода отдаётся владельцу, — то есть до этого паттерна и, как правило, задолго до него. Здесь
+работа доводится до готовности и черновик снимается.
+
+## 10. Работа отдаётся на разбор
+
+PR открыт черновиком — и с этой минуты работа ждёт владельца, а не машину. Заход на этом не
+кончается: следующая задача эпика берётся тем же движением, паттерн `task-flow-resume`.
+
+**Заход, открывший PR, называет оставшийся шаг в двух местах — разделом в теле PR и словами
+владельцу:** после одобрения ветка получает ещё один коммит — разбор папки, — и только потом
+вливается. Порядок этот записан здесь, а читает его исполнитель; вливает же владелец, и
+молчание он читает как «работа кончена» — видит зелёный PR и мержит его тем же ходом. Промах
+случается ровно в шов между двумя ходами, и стоит он отдельной задачи: после слияния папку
+разбирать уже некому.
+
+### Два сообщения владельцу, и между ними — прогон
+
+Оба обязательны, и порядок между ними один. Ни одно не заменяется другим: первое говорит, что
+работа отдана и чего она ждёт, второе — что она готова.
+
+Сразу после открытия PR:
+
+```
+PR #<номер> открыт черновиком. Жду прогона: пока он идёт, о работе известно только то, что
+она запушена. Как закончится — разберу папку задачи последним коммитом, сниму черновик и
+попрошу тебя влить. Пока жду, беру задачу #<номер следующей>.
+```
+
+Прогон зелёный, папка разобрана и запушена, черновик снят:
+
+```
+PR #<номер> готов к слиянию: прогон зелёный, папка задачи разобрана, за работой убрано,
+черновик снят. Влей его, пожалуйста.
+```
+
+Черновик снимается перед вторым сообщением, а не после него: владелец, прочитав просьбу
+влить, идёт нажимать кнопку — у черновика она заблокирована, и ход возвращается к исполнителю
+ни за чем.
+
+Прогон красный — сообщение то же по форме, но говорит о красном и о том, что с ним делается;
+просьбы влить в нём нет. Просьба звучит один раз и только тогда, когда работа готова целиком:
+сказанная заранее, она перестаёт что-либо значить, и владелец возвращается к прежнему —
+вливать по зелёной странице.
+
+Между двумя сообщениями исполнитель не ждёт: работа отдана на разбор, и тем же движением
+берётся следующая задача. Возвращается он к PR тем ходом, которым читает конец прогона.
+
+### Оставшийся шаг стоит разделом в теле PR
+
+Сказанного вслух мало, и одним этим требование не держится. Реплика живёт до следующей реплики,
+а решение о слиянии принимается на странице PR — там переписки нет вовсе. Поэтому оставшийся
+шаг пишется дважды: разделом в теле PR и словами владельцу. Одно другого не заменяет — тело
+пишется один раз и лежит у самой кнопки, разговор идёт дальше и уносит сказанное с собой.
+
+Раздел стоит последним и говорит ровно одно — что случится с веткой после одобрения:
+
+```markdown
+## Оставшийся шаг
+
+После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
+вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
+```
+
+Разобрана папка — раздел переписывается тем же вызовом, которым правится тело:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
+```
+
+Пустым раздел не оставляется и не удаляется вовсе: отсутствие раздела и «шагов не осталось»
+читаются одинаково, а значат разное. Образец тела PR целиком — в паттерне заведения коммита
+и PR, если дерево его разложило.
+
+Проверить это машиной нечем, и проверки не будет: тело PR не читает ни одна сверка, а хостинг
+не спрашивает ни о чём, кроме заголовка. Требование держится тем же, чем и слова вслух, — тем,
+кто пишет тело. Разница между ними одна, и она вся: реплику владелец прочитает, только если
+вернётся в переписку, а раздел он видит там, куда смотрит, нажимая кнопку.
+
+## 12. Договорённость вливается в спек домена
 
 Последним коммитом PR, до слияния. Код к этому моменту написан, поэтому привязки
 `файл:символ` известны — правило въезжает в спек домена сразу проверяемым.
@@ -38,13 +119,13 @@ npm run check:specs   # раздел «Пора вливать» называе
   таблице `docs/specs/README.md`.
 
 Работа шла несколькими задачами — вливание идёт в последней из них. Какая последняя, видно в
-`docs/plans/<линия>.md`; закрытая линия уезжает в `docs/archive/` или удаляется.
+замысле эпика; закрытый эпик уезжает в описание прошлого или удаляется.
 
 ```bash
 npm run check:specs   # после вливания: привязки на месте, сценарии не потерялись
 ```
 
-## 10. Тексты домена приводятся к сделанному
+## 13. Тексты домена приводятся к сделанному
 
 В спек уезжает только то, что записали до кода. Остальные тексты — правила, паттерны, законы
 приложения — после правки никто не перечитывает, и они продолжают описывать старое дерево.
@@ -85,41 +166,7 @@ grep -rn -A3 "Чего из закона здесь нет" <каталог пр
 Что сделали на этом шаге, пишется в тело PR: что перечитали, что изменили, а если ничего
 не изменили — почему. Форма раздела — паттерн `git-workflow-commit`.
 
-## 11. Папка задачи разбирается
-
-**Заход, открывший PR, называет владельцу оставшийся шаг вслух:** после одобрения ветка
-получает ещё один коммит — разбор папки, — и только потом вливается. Порядок этот записан
-здесь, а читает его исполнитель; вливает же владелец, и молчание он читает как «работа
-кончена» — видит зелёный PR и мержит его тем же ходом. Промах случается ровно в шов между
-двумя ходами, и стоит он отдельной задачи: после слияния папку разбирать уже некому.
-
-### Два сообщения владельцу, и между ними — прогон
-
-Оба обязательны, и порядок между ними один. Ни одно не заменяется другим: первое говорит, что
-работа отдана и чего она ждёт, второе — что она готова.
-
-Сразу после открытия PR:
-
-```
-PR #<номер> открыт. Жду прогона: пока он идёт, о работе известно только то, что она
-запушена. Как закончится — разберу папку задачи последним коммитом и попрошу тебя влить.
-Пока жду, беру задачу #<номер следующей>.
-```
-
-Прогон зелёный, папка разобрана и запушена:
-
-```
-PR #<номер> готов к слиянию: прогон зелёный, папка задачи разобрана, за работой убрано.
-Влей его, пожалуйста.
-```
-
-Прогон красный — сообщение то же по форме, но говорит о красном и о том, что с ним делается;
-просьбы влить в нём нет. Просьба звучит один раз и только тогда, когда работа готова целиком:
-сказанная заранее, она перестаёт что-либо значить, и владелец возвращается к прежнему —
-вливать по зелёной странице.
-
-Между двумя сообщениями исполнитель не ждёт: работа отдана на разбор, и тем же движением
-берётся следующая задача. Возвращается он к PR тем ходом, которым читает конец прогона.
+## 14. Папка задачи разбирается
 
 Разбор идёт по трём исходам, а не по двум.
 
@@ -142,11 +189,12 @@ PR #<номер> готов к слиянию: прогон зелёный, па
 кто-то читает, а не свалка ходов работы. Таблица ниже говорит о том, что осталось после
 первого отбора.
 
-| Файл          | Куда                                                                                                               |
-| ------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `grill.md`    | в `docs/archive/` — ответы владельца невосстановимы, и это единственная запись о том, почему задача поставлена так |
-| `progress.md` | в `docs/archive/`, если в нём есть решения по ходу с причинами; иначе удаляется                                    |
-| `plan.md`     | удаляется — после выкатки на его вопрос отвечает код, а на «как работает» отвечает спек домена                     |
+| Файл            | Куда                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `grill.md`      | в `docs/archive/` — ответы владельца невосстановимы, и это единственная запись о том, почему задача поставлена так |
+| `progress.md`   | в `docs/archive/`, если в нём есть решения по ходу с причинами; иначе удаляется                                    |
+| `plan.md`       | удаляется — после выкатки на его вопрос отвечает код, а на «как работает» отвечает спек домена                     |
+| находки разбора | переезжают к замыслу эпика — их читает владелец, когда эпик кончится; работа вне эпика показывает их сразу         |
 
 Уезжающее складывается одним файлом с говорящим именем, а не папкой из трёх:
 
@@ -175,7 +223,7 @@ rm -r docs/tasks/<своя>
 Две записи в архиве, а не одна: работы разные, и решения в них разные. Сверка очереди работ
 после этого не называет ни одной папки — этим и проверяется, что разобраны обе.
 
-## 12. Сверка
+## 15. Сверка
 
 ```bash
 npm run check:board   # папка закрытой задачи среди текущих, брошенные черновики
@@ -183,6 +231,65 @@ npm run check:specs   # договорённость влита, привязк
 npm run check:docs    # пути, названные в текстах, существуют
 ```
 
+## 16. Работа разбирается правилами — фоном, следом за PR
+
+Шаг о слое правил, а не о продукте: что за эту работу грузилось, что помогло, чего не хватило и
+где текст правила разошёлся с деревом. Знает это только тот заход, который работу вёл, — через
+сутки не знает никто.
+
+Ведёт разбор роль разбора закрытой задачи, если дерево её разложило; не разложившее ведёт его
+само, теми же вопросами. Файлов роль не правит — приносит готовые формулировки, а вставлять их
+решает владелец.
+
+**Запускается разбор в фоне, сразу за открытием PR, и ход на нём не кончается.** Роль ничего не
+спрашивает, пока работает, и быстрее от ожидания не идёт: следующая задача берётся тем же ходом,
+которым запущен разбор.
+
+Порядок один и переставлять его нельзя:
+
+1. **Сводка собирается до запуска** — пока задача ещё в голове. Что делали, что пошло не так,
+   что грузилось и что каждое правило дало, на какие грабли окружения наткнулись. Собранная
+   через две задачи, она пересказывает историю ветки вместо того, что было на самом деле.
+2. **Роль уходит в фон** — инструментом запуска роли, с путём к списку загруженного и сводкой
+   целиком. Ход продолжается следующей задачей.
+3. **Вернувшиеся находки принимают одним ходом** — записать и вернуться к прежнему. Разбор,
+   отложенный «до удобного момента», не случается вовсе: заход кончается раньше.
+
+## 17. Находки разбора ложатся в папку задачи и ждут владельца
+
+Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск — в папку
+задачи, файлом рядом с ходом работы. Пишет его исполнитель: роль файлов не пишет.
+
+Папка задачи умирает со слиянием, а находки должны пережить весь эпик — владелец читает их
+разом, когда эпик кончился. Поэтому при разборе папки (шаг 14) файл находок не удаляется вместе
+с остальным, а **переезжает к замыслу эпика**: там его найдут и после того, как ветка въехала.
+Работа вне эпика показывает находки владельцу сразу, тем же ходом.
+
+**Наружу без слова владельца уезжает только сводка наблюдений.** Она говорит, чем пользовались
+и чем не пользовались ни разу, — это факт, и мнением он не станет. Предложение — другое дело:
+это заготовка правки чужого дерева, и часть заготовок отпадает при первом же чтении. Уехавшая
+без разбора, она становится работой того, кто её не заказывал.
+
+Порядок такой: находки копятся у замысла эпика → эпик кончился → владелец читает их разом и
+говорит, что из них верно → названное им оформляется предложением и уезжает. Чем отправляют —
+скил слоя правил, если дерево его разложило.
+
+У каждой находки называется адрес, и адресов три:
+
+| Куда                       | Что туда идёт                                                            |
+| -------------------------- | ------------------------------------------------------------------------ |
+| слой правил — предложением | то, что верно любому дереву этого класса: статья, пункт правила, паттерн |
+| имена этого дерева         | то, что верно здесь: компаньон правила, профиль, карта гейта             |
+| надстройка над разложенным | то, что здесь звучит иначе, чем в пакете                                 |
+
+Без адреса правка ложится туда, где её видит автор, — то есть в своё дерево, — и общее оседает
+в одном месте, оставаясь неизвестным всем остальным.
+
+**Разбор без правки закрытым не считается.** Из него выходит либо правка слоя правил, либо
+предложение наружу; не вышло ни того ни другого — это жалоба, и она повторится. Предложение, о
+котором владелец сказал вслух, уходит наружу в тот же ход: написанное и не отправленное лежит в
+дереве неотличимо от отправленного.
+
 ## Ловушки
 
 - **Папку разбирают до слияния — потом о ней уже никто не вспомнит.** Сверка очереди считает
@@ -235,9 +342,9 @@ npm run check:docs    # пути, названные в текстах, суще
 - **Правило без привязки в спек домена не въезжает.** Кода, который его исполняет, нет —
   значит это намерение, и место ему в открытых вопросах домена, а не в правилах.
 - **Замысел эпика правят только там, где вписывают «чем кончился».** Границы эпика и
-  порядок задач в ней при этом остаются прежними, а работа их уже нарушила: задача, решившая
+  порядок задач в нём при этом остаются прежними, а работа их уже нарушила: задача, решившая
   читать спеки, оставила над собой границу «спеки — вторая очередь», и следующий исполнитель
-  прочитает её как действующую. Границы линии перечитываются целиком тем же заходом, что и
+  прочитает её как действующую. Границы эпика перечитываются целиком тем же заходом, что и
   итог работы.
 - **Архив не обновляется после выкатки.** Уехавшее туда описывает день переезда, и правится
   оно только вместе с признанием, что описывало неверно.

package/assets/patterns/task-flow-handoff.md

@@ -41,7 +41,7 @@ description: Паттерн правила task-flow. Брать, когда з
 Незакрытый этап — тоже законная точка, если в ходе работы записано, что именно из него сделано и
 чем это подтверждено. Незаконная точка одна: правка, о которой не записано ничего.
 
-## 8. Заход закрывается передачей
+## 9. Заход закрывается передачей
 
 Уборку этого шага — главную ветку, влитые ветки и запись самой передачи — делает команда
 `next-session`: она проходит его целиком и называет путь к передаче последней строкой. Ниже —

package/assets/patterns/task-flow-resume.md

@@ -34,7 +34,7 @@ description: Паттерн правила task-flow. Брать при возв
   ней проверяется деревом — сборкой, тестами, чтением файла, — а не вопросом.
 - **Не править замысел.** С ним сверяют результат; пересмотр идёт записью в ходе работы.
 
-## 6. Возвращение к работе новым заходом
+## 7. Возвращение к работе новым заходом
 
 Сверить «Где стоим» с деревом. Запись описывает день, когда её сделали:
 
@@ -46,7 +46,7 @@ git log --oneline origin/main..HEAD
 Разошлось — «Где стоим» правится сразу, до работы: следующий заход поверит записи, а не
 дереву.
 
-## 7. Этап делается и отмечается в ходе работы
+## 8. Этап делается и отмечается в ходе работы
 
 Раздел «Где стоим» **перезаписывается**, а не дописывается — это первое, что читает следующий
 заход, и единственное, что переживает обрезку по объёму:
@@ -94,7 +94,7 @@ git log --oneline origin/main..HEAD
 - Доэтапное, не этой работы: сверка очереди перечисляет шесть закрытых задач вне борды.
 ```
 
-## 13. Следующая задача эпика берётся тем же движением
+## 11. Следующая задача эпика берётся тем же движением
 
 Задача закрыта, PR открыт и ждёт владельца — заход на этом не кончается. Отданное на разбор
 ждёт человека, а не машину: пока эпик не кончился, следующая его задача берётся сразу, тем же

package/assets/patterns/task-flow-start.md

@@ -107,7 +107,34 @@ Workflow(name: "plan", args: "docs/tasks/_draft-<slug>")
 «не входит». Находка критика, расходящаяся с ответом владельца, относится владельцу — она не
 исполняется молча и не считается закрытой правкой текста.
 
-### 4. Задача, ветка, папка
+### 4. Серия задач объявляется эпиком
+
+Разбор кончился одной задачей — шаг пропускается. Вышло несколько, и порядок между ними
+значим — эпик объявляется здесь, до первой из них, и дважды: карточкой в очереди работ с меткой
+эпика и замыслом эпика рядом с ней.
+
+Замысел эпика называет три вещи, и ни одна не выводится из остальных:
+
+```markdown
+# <Возможность, которая разрабатывается>
+
+Одной фразой: что у владельца появится, когда эпик кончится.
+
+| №   | Задача       | Почему здесь             |
+| --- | ------------ | ------------------------ |
+| 1   | <что делает> | <на чём стоят следующие> |
+| 2   | <что делает> | <что из первой ей нужно> |
+```
+
+Состав без порядка порядком не является: две задачи, у которых он держался пониманием, ушли в
+работу наоборот, и вторая переделывалась под первую. Назначенный здесь порядок держится до конца
+эпика; пересмотр — решение владельца, и записывается он в ход работы той задачи, которая его
+вызвала.
+
+Лежит замысел вне папки задачи: та умирает с мержем первой же задачи. Каталог для него называет
+компаньон правила — у пакета своего пути нет.
+
+### 5. Задача, ветка, папка
 
 ```bash
 npm run task:new -- --title '<Что не так>' --slug <slug> --label documentation --label area:tooling < тело.md
@@ -135,7 +162,7 @@ cp docs/tasks/_template/plan.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/plan.m
 cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/progress.md
 ```
 
-### 5. Шапка замысла
+### 6. Шапка замысла
 
 Её читает гард:
 
@@ -159,9 +186,9 @@ cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/pr
   заведённая заранее задача после разбивки закрывается и остаётся мусором в очереди работ.
 - **Разбор пишется на диск сразу, а не копится в переписке.** Сессия обрывается, и разбор,
   прожитый в разговоре, восстанавливается только пересказом владельца.
-- **Из одного разбора вышло несколько задач — общее уезжает в `docs/plans/<линия>.md`.**
-  Папка задачи умирает с мержем, а порядок задач и зависимости между ними должны его
-  пережить.
+- **Из одного разбора вышло несколько задач — общее уезжает в замысел эпика.** Папка задачи
+  умирает с мержем, а порядок задач и зависимости между ними должны его пережить. Каталог для
+  замысла называет компаньон правила.
 - **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
   привязана, и задача попадает на неё только явным добавлением.
 - **Slug ветки берётся из терминологии договорённости, а не из слов просьбы.** Договорённость