@rt-tools/agent-kit 0.11.0 → 0.13.0

package/assets/rules/task-flow.md

@@ -2,7 +2,7 @@
 name: task-flow
 kind: rule
 law: work-conduct
-description: Правило под «Закон о ведении работы». Брать в начале любой работы от владельца, при правке docs/tasks/**, docs/specs/*/proposed/** и при возвращении к незаконченной задаче. Называет разбор просьбы до первой правки, папку задачи по имени ветки, договорённость о продукте до кода, шесть обязательных вопросов и разбор папки при закрытии. Готовый порядок — в паттернах task-flow-start, task-flow-resume и task-flow-close.
+description: Правило под «Закон о ведении работы» — та его часть, что про ход работы от просьбы владельца до слияния. Брать в начале любой работы от владельца, при правке папок задач и договорённостей о продукте, при возвращении к незаконченной задаче. Называет разбор просьбы до первой правки, папку задачи по имени ветки, состояния работы и их обязательные действия, договорённость о продукте до кода, разбор папки при закрытии. Готовый порядок — в паттернах task-flow-start, task-flow-resume, task-flow-close и task-flow-archive. Чем кончается ход и что стерегут стражи — правило turn-conduct.
 ---
 
 # Ведение работы — как это устроено здесь
@@ -11,6 +11,10 @@ description: Правило под «Закон о ведении работы»
 про ход работы; здесь — чем это названо в этом дереве, где лежит и что из закона у нас не
 проверяется.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки и поведение по разборам происшествий.
+Грузится по требованию, а не вместе с правилом: при обычном решении она не нужна — она нужна
+тому, кто разбирает промах или спорит с гардом.
+
 **Требует:** `hooks/task-flow-guard.sh`, `hooks/task-context-load.sh`, `hooks/grill-gate.sh`, `hooks/window-fill-guard.sh`, `hooks/turn-exit-guard.sh`
 
 ## Как это называется здесь
@@ -40,12 +44,8 @@ description: Правило под «Закон о ведении работы»
 пока действие не сделано, работа стоит в том же состоянии. Список шагов этого не давал: шаг
 кончался, а что делать дальше, выводилось из соседних строк.
 
-Состояние объявляется машиночитаемой строкой в разделе «Где стоим» хода работы и
-перезаписывается вместе с ним:
-
-```markdown
-- **Состояние:** `этап-идёт`
-```
+Состояние объявляется в разделе «Где стоим» хода работы машиночитаемой строкой
+``- **Состояние:** `этап-идёт` `` и перезаписывается вместе с ним.
 
 | Состояние                 | Вход в него                                     | Обязательное действие                                  | Ведёт паттерн      |
 | ------------------------- | ----------------------------------------------- | ------------------------------------------------------ | ------------------ |
@@ -55,49 +55,28 @@ description: Правило под «Закон о ведении работы»
 | `задача-взята`            | задача в колонке работы, ветка по номеру, папка | написать замысел                                       | `task-flow-start`  |
 | `замысел-записан`         | замысел лежит и после записи не правится        | делать первый этап                                     | `task-flow-start`  |
 | `этап-идёт`               | этап начат                                      | доделать этап и отметить в ходе работы                 | `task-flow-resume` |
-| `этапы-кончились`         | все этапы отмечены                              | прогнать набор и открыть PR черновиком                 | `task-flow-close`  |
+| `этапы-кончились`         | все этапы отмечены                              | прогнать набор, влить договорённость, привести тексты  | `task-flow-close`  |
+| `разбор-кончился`         | набор зелёный, тексты приведены                 | разобрать папку последним коммитом                     | `task-flow-archive` |
+| `папка-разобрана`         | папки в ветке нет, запись в архиве есть         | открыть PR черновиком                                  | `task-flow-close`  |
 | `работа-отдана`           | PR открыт черновиком                            | взять следующую задачу                                 | `task-flow-resume` |
-| `разбор-кончился`         | прогон зелёный, замечаний нет                   | влить договорённость, привести тексты, разобрать папку | `task-flow-close`  |
-| `папка-разобрана`         | папки в ветке нет, запись в архиве есть         | снять черновик и попросить влить                       | `task-flow-close`  |
-| `влито`                   | PR слит человеком                               | разбор работы правилами и сверка очереди               | `task-flow-close`  |
+| `влито`                   | PR слит человеком                               | разбор работы правилами и сверка очереди               | `task-flow-archive` |
 
 Ни у одного состояния обязательное действие не звучит как «ждать»: ожидание чужого шага
-состоянием работы не является. Прогон, разбор владельцем и слияние идут без исполнителя, и от
-взгляда быстрее не становятся — поэтому в `работа-отдана` обязательное действие смотрит на
-следующую задачу, а не на открытый PR.
-
-Заполнение окна захода состоянием работы тоже не бывает: заход кончается передачей, работа
-остаётся в том состоянии, в каком стояла, а следующий заход читает строку и продолжает с неё.
-Ведёт закрытие захода паттерн `task-flow-handoff`.
+состоянием работы не является — прогон, разбор владельцем и слияние идут без исполнителя и от
+взгляда быстрее не становятся, поэтому в `работа-отдана` обязательное действие смотрит на
+следующую задачу, а не на открытый PR. Заполнение окна захода состоянием тоже не бывает: заход
+кончается передачей, работа остаётся в том состоянии, в каком стояла, а следующий заход читает
+строку и продолжает с неё. Чем ход кончается и что его концом не бывает — правило
+`turn-conduct` под тем же законом.
 
 Перечень показывается владельцу в начале работы, и на нём же отмечается, где стоим: иначе после
 шести вопросов не видно ни того, что будет дальше, ни сколько всего впереди.
 
-## Выходы хода
-
-Ход кончается четырьмя способами, и других нет:
-
-| Выход                                              | Чем подтверждается                                              |
-| -------------------------------------------------- | --------------------------------------------------------------- |
-| вопрос владельцу, ответа на который в правилах нет | вопрос задан, и за тот же ход правила читались                  |
-| отказ гарда                                        | отказ назван владельцу, обход не искался                        |
-| заполненное окно там, где сжатия нет               | ход работы дописан, передача написана                           |
-| работа отдана, и следующая начата                  | PR открыт, и по следующей задаче сделано действие, а не сказано |
-
-Всё остальное — продолжение хода, а не его конец. Веха ходом не кончается: ни коммит, ни
-прочитанная договорённость, ни граница «прочитал — сейчас правлю», ни зелёная проверка. Слова
-«иду дальше» и «работаю дальше» владелец читает как совершающееся действие, и писать их вместо
-результата нельзя.
-
-Переход из состояния в состояние ходом не кончается тем более: обязательное
-действие сделано, и следующее делается тем же ходом. Граница состояния выглядит законченным
-куском лучше всякой другой вехи — сделанное названо, отчитаться есть чем, — и отчёт встаёт
-ровно туда, где должно было стоять следующее действие. Что делается сразу за обязательным
-действием, называет сам раздел состояния строкой следующего движения.
-
-Три способа кончить ход выглядят работой и ею не являются: сводка о чужом шаге, меню при
-назначенном порядке и объявление намерения. Что при этом должно быть верно — ниже, в статьях
-о применении закона.
+Последние два состояния объявить на диске уже нечем: ход работы уезжает вместе с папкой, а
+папка разбирается раньше, чем открывается PR. Признак у них поэтому в истории ветки — коммит
+разбора папки, — и читает его гард, а не строка в файле. Цена названа прямо: с этой минуты и до
+слияния состояние работы виду не подлежит, и хвост из четырёх шагов — открыть PR, дождаться
+прогона, снять черновик, попросить влить — держится паттерном, а не объявлением.
 
 ## Ход
 
@@ -120,16 +99,16 @@ flowchart TD
     H --> I{Этап сделан}
     I -->|Да| J[Отметка в ходе работы — единственном месте, где отмечается сделанное]
     J --> I
-    I -->|Этапы кончились| K[PR открывается; исполнитель называет номер, чего ждёт и что сделает следом]
+    I -->|Этапы кончились| T[Набор прогоняется, договорённость вливается в спек домена, тексты приводятся к сделанному]
+    T --> N[Папка задачи разбирается последним коммитом: разбор просьбы — в описание прошлого, находки — к замыслу эпика, замысел — прочь]
+    N --> S[Сверка очереди работ]
+    S --> K[PR открывается черновиком; исполнитель называет номер, чего ждёт и что сделает следом]
     K --> W[Разбор закрытой работы правилами уходит в фон, находки ложатся на диск]
     W --> L[Пока PR ждёт разбора, берётся следующая задача]
     L --> M{Разбор и прогон кончились}
-    M -->|Красный прогон или замечания| V[Чинится в той же ветке: замысел на диске ещё нужен]
+    M -->|Красный прогон или замечания| V[Чинится в той же ветке: замысла на диске уже нет, и признак работы гард берёт из истории ветки]
     V --> M
-    M -->|Зелено и замечаний нет| T[Договорённость вливается в спек домена, тексты приводятся к сделанному]
-    T --> N[Папка задачи разбирается последним коммитом: разбор просьбы — в описание прошлого, находки — к замыслу эпика, замысел — прочь]
-    N --> S[Сверка очереди работ]
-    S --> O[Черновик снимается, слияние нажимает человек]
+    M -->|Зелено и замечаний нет| O[Черновик снимается, слияние нажимает человек]
 ```
 
 ## Как закон применяется здесь
@@ -139,9 +118,11 @@ flowchart TD
   в ходе работы состояние и названную в замысле договорённость о продукте.
 - **Гард судит объявленный переход, а не наличие файлов.** Артефакт на диске не говорит, дошла
   ли работа до правки кода: пустой замысел, положенный ради снятия отказа, лежит так же, как
-  написанный. Отказ снимает объявленное состояние, и снимают его четыре — `этап-идёт`,
-  `этапы-кончились`, `работа-отдана` и `разбор-кончился`: прогон бывает красным, а разбор — с
-  замечаниями, и починка идёт в ту же ветку.
+  написанный. Отказ снимает объявленное состояние, и снимают его три — `этап-идёт`,
+  `этапы-кончились` и `разбор-кончился`. Четвёртый путь у отказа не состояние, а история ветки:
+  папка, разобранная её коммитом, означает отданную работу, и правка по замечаниям разбора идёт
+  без замысла на диске — объявить состояние после уборки уже нечем. Прогон бывает красным, а
+  разбор — с замечаниями, и починка идёт в ту же ветку.
 - **Отказ по состоянию называет обязательное действие того состояния, которое объявлено.**
   Исполнитель, которому сказано только «не в том состоянии», перепишет строку состояния вместо
   того, чтобы сделать шаг.
@@ -163,13 +144,20 @@ flowchart TD
   дважды стало поводом обойти отказ гарда, вместо того чтобы завести папку и пойти дальше.
   Заводится она всегда и до первой правки; сколько заходов уйдёт на работу, заранее не знает
   никто.
+- **Папка задачи разбирается последним коммитом до открытия PR, а не после одобрения.** Прежде
+  она стояла после: пока идёт разбор, замысел нужен на диске, иначе правку по замечаниям
+  отбивает гард. Но кнопку слияния нажимает человек на хостинге, куда гард не достаёт, и
+  вливает он, как только видит зелёное, — закрывающему коммиту места не остаётся вовсе. Трижды
+  подряд папка уехала в главную ветку неразобранной, и разобрать её было уже некому: работа
+  перешла к следующей задаче, а PR закрылся. Цена перестановки названа прямо: замысла с этой
+  минуты на диске нет, и признак отданной работы гард берёт из истории ветки.
 - **Открыв PR, исполнитель называет владельцу три вещи: номер, чего ждёт и что сделает
   следом.** Ждёт он прогона — до его конца о работе ничего не известно, кроме того, что она
-  запушена. Следом идёт уборка: разбор папки задачи последним коммитом. Сказанное так владелец
-  читает однозначно, а зелёный прогон на странице — нет: он говорит, что не сломано, и молчит
-  о том, что ветка ждёт ещё одного коммита. Трижды подряд PR был влит внутри этого молчания.
-- **Просьба о слиянии — отдельный ход, и раньше уборки её не бывает.** Порядок один: PR открыт
-  черновиком → прогон зелёный → папка задачи разобрана и запушена → черновик снят →
+  запушена. Следом идёт снятие черновика. Сказанное так владелец читает однозначно, а зелёный
+  прогон на странице — нет: он говорит, что не сломано, и молчит о том, что кнопка слияния у
+  черновика заблокирована.
+- **Просьба о слиянии — отдельный ход, и раньше зелёного прогона её не бывает.** Порядок один:
+  папка задачи разобрана и запушена → PR открыт черновиком → прогон зелёный → черновик снят →
   исполнитель просит влить, называя номер. До этой просьбы работа не готова, сколько бы зелёного
   на её странице ни было.
 - **PR открывается черновиком, а не в конце работы.** Пока правка кода не выложена в PR,
@@ -181,111 +169,8 @@ flowchart TD
   правку кода приложения, и работа, которая туда не доходит, проходит мимо него — но папку
   заводит всё равно: статья правила говорит «под любую работу, без исключений». Прочитанный
   как признак, гард становится разрешением работать без замысла везде, куда он не смотрит.
-- **Сводка о чужом шаге.** Прогон, разбор владельцем и слияние идут без исполнителя и от взгляда
-  быстрее не становятся. Ход, кончившийся такой сводкой, владелец читает как работу: она полна,
-  в ней названы номера и состояния, и пустоты за ней не видно. О чужом шаге говорят вместе с
-  начатым своим, а не вместо него. За один заход это было нарушено четырежды, и готовая работа
-  простояла в невлитом PR почти три часа.
-- **Меню при назначенном порядке.** Выбор, предложенный владельцу, пока эпик не кончился, — это
-  просьба назначить порядок заново. Работы в эпике не осталось — так и говорится: эпик
-  кончился, — а не «чем займёмся».
-- **Объявление намерения.** «Беру следующую задачу» — не то же самое, что взять её: фраза живёт
-  до конца хода, а работа не двигается. Названо может быть только сделанное: номер заведённой
-  задачи, имя заведённой ветки, переведённая колонка.
-
-- **Прерывание работы владельцем называется вслух.** Пришло задание, останавливающее начатое, —
-  исполнитель говорит, что стоит, на чём остановлено и что будет с прежней работой, и только
-  потом берётся за новое. Молчание об этом владелец читает как «прежнее кончилось».
-- **Остановка называется отдельной репликой.** Не строкой в конце отчёта: там она тонет —
-  владелец читает отчёт как рассказ о сделанном. Называются три вещи: что стоит, чего оно ждёт
-  и что владелец может решить.
-- **Выходы хода стережёт страж, а не память исполнителя.** Он читает объявленное состояние
-  работы и то, что за ход по ней сделано: правку файла или команду, меняющую дерево. Ход, в
-  котором не было ни того ни другого, возвращается исполнителю вместе со следующим шагом из
-  хода работы. Отданную и влитую работу страж не судит: она уже дождалась чужого шага.
-- **Этап замысла объявляется закрытым только после того, как его команда проверки прошла.**
-  Строка «Чем проверяется» несёт команду обратными кавычками и то, что в её выводе означает
-  «сошлось». Страж читает прежний номер этапа из истории ветки и не выпускает ход, в котором
-  номер вырос, а команда не запускалась: через заход отмеченное по памяти неотличимо от
-  проверенного.
-- **Слово об остановке страж читает у владельца, а не у исполнителя.** Иначе остановку
-  объявляет тот, кому она в эту минуту удобна, и запрет держится ровно до первого неудобства.
-- **Утверждение о состоянии дерева стережёт гард утверждения, а не память исполнителя.** Всё,
-  что ответ владельцу говорит о дереве, несёт команду и её вывод: сказанное без команды
-  утверждением не считается — ни «проверено», ни «снято», ни «готово». Гард читает текст,
-  сказанный владельцу за ход, и ищет команду того же хода; у каждого слова назван свой род
-  команды, потому что общий признак «команда была» подтверждал бы одно другим. Прошлый ход не
-  годится: состояние дерева меняется, и вчерашний вывод о нынешнем молчит. Восемь разборов
-  подряд пришлись на этот промах, и каждый раз в правило дописывалась ещё одна статья —
-  держит его теперь машина.
-- **Слово-утверждение гард ловит, неверный вывод — нет.** Об образце, судимом по одному его
-  файлу, и о пути, которым человек не пойдёт, судить нечем: там нет ни слова, ни команды, с
-  которой сверять. Это известная граница гарда, и держат её статьи ниже, а не он.
-- **Ход о чужом шаге стережёт гард ожидания, а не память исполнителя.** Он отбивает завершение
-  хода, в котором о чужом шаге сказано, а по следующей задаче не сделано ни одного действия —
-  ни заведения задачи, ни ветки, ни папки, ни перевода колонки. Чужой шаг он узнаёт по двум
-  признакам: в ходе открыт PR либо в ходе прочитан красный прогон. Оба берутся из самого хода:
-  спросить хостинг было бы точнее, но сетевой вызов на завершении хода падает вместе со связью
-  и отбивал бы работу вместо промаха, а вывод команды о прогоне в записи хода уже лежит. Слова
-  «беру следующую задачу» гард действием не считает — ровно потому, что их и произносят вместо
-  неё.
-- **Конец прогона узнаётся возвратом фоновой команды, а не взглядом на страницу.** Ожидание,
-  запущенное в фоне отдельным ходом, возвращает исполнителя к PR само; до тех пор ход занят
-  следующей задачей. Взгляд на страницу этого не даёт: он либо повторяется вхолостую, либо не
-  повторяется вовсе, и оба исхода со стороны выглядят одинаково — работа не двигается.
-- **Отказ гарда кончает ход.** Другого пути к отбитой правке не ищут: ни командой оболочки, ни
-  соседним инструментом, ни правкой самого гарда. Отбитая правка либо делается после того, как
-  условие отказа выполнено, либо не делается вовсе — и тогда владельцу называется отказ, а не
-  результат. Обход стоит дороже отказа: гард отбивает один файл, а обойдённый гард снимает
-  требование со всего дерева и молчит об этом. Держится это не только памятью — гарды судят и
-  команду оболочки, которая пишет файл.
-- **Ход, в котором владельцу задан вопрос, не заканчивается, пока за этот же ход не читались
-  законы и правила.** Чтением считается любой из трёх путей: загрузка правила, чтение файла
-  законов или правил, поиск по ним. Отбивает гард разговора — на завершении хода, а не на
-  инструменте вопроса: спрашивают чаще прозой, чем меню. Найденное ложится в раздел «Что уже
-  сказано в правилах» разбора.
-- **Действия, которые исполнитель не делает без слова владельца, перечислены в компаньоне
-  правила.** Список у каждого дерева свой — пакет знает только требование, чтобы список был
-  назван. Не названный, он выводится из общих слов, и «делай, что нужно по плану» становится
-  разрешением на пуш и правку общих документов заодно с коммитом. Оценка «это безопасно» списка
-  не заменяет: её назначает тот, кому она в эту минуту удобна, и она плывёт. За один заход одна
-  и та же команда была сначала слишком опасной, чтобы её позвать, а через два хода —
-  достаточно безопасной, чтобы позвать без спроса.
-- **У отказа от необратимого действия есть безопасная часть, и она делается.** Требование
-  спросить владельца относится к действию, а не к ходу: работа, у которой отделима часть без
-  последствий, делится, а не откладывается целиком. Список вариантов, поданный вместо работы,
-  читается как работа — тем полнее, чем аккуратнее он составлен: он пронумерован, в нём названы
-  цифры, и именно поэтому пустота хода за ним не видна. Владельцу называется, что уже сделано и
-  что осталось за его словом, — а не выбор из вариантов вместо и того и другого.
-- **Ход, в котором исполнитель признал промах, не заканчивается, пока записи о происшествии
-  нет.** Отбивает гард происшествия — на завершении хода: к моменту признания промах уже
-  случился, и ловить раньше нечего. Признание ловится набором образцов, а не пониманием смысла;
-  промах, признанный словами вне набора, гард пропускает, и это его известная граница, а не
-  обещание.
-- **Заход, начатый с передачи, входит в работу тем же правилом, что и всякий другой.** Передача
-  лежит вне дерева, её не читает ни одна проверка, и написана она вчера: всё, что в ней стоит,
-  проверяется деревом. Порядок входа — четыре шага в паттерне возвращения; стережёт его гард, а
-  не память: порядок, записанный только словами, исполняется, пока о нём помнят.
-- **Состояние незаконченной работы приходит в контекст на запуске сессии.** Замысел и ход
-  работы отдаются целиком, разбор просьбы — путём. Ветка вида `<КЛЮЧ>-*` без папки даёт
-  предупреждение с готовой командой, но сессию не рвёт.
 - **Сделанное отмечается только в ходе работы.** «Где стоим» перезаписывается каждым заходом,
   а не дописывается: это первое, что читает следующий заход.
-- **Заполненное окно кончает ход только там, где сжатия нет.** Где оно объявлено, окно —
-  продолжение хода: заход сжимается и работает дальше, а порог остановки срабатывает лишь тогда,
-  когда сжатие не пришло.
-- **Заполнение окна захода стережёт гард, а не память исполнителя.** На первом пороге он
-  напоминает выбирать точку остановки, на втором отбивает всё, кроме записи хода работы,
-  передачи и команд поставки. Размер окна и оба порога дерево задаёт само; не задавшее размера
-  стража не получает.
-- **Порог сжатия контекста дерево задаёт само, и стоит он НИЖЕ порога остановки.** Совпавшие
-  пороги согласием не бывают: это гонка, и выигрывает её страж — он стоит на вызове, а сжатие
-  приходит между ходами. Расстояние объявляется числом, а не выводится разницей; сведены пороги
-  или нет, говорит разбор состояния раскладки.
-- **Заход закрывается передачей, которая лежит вне дерева.** Состояние работы коммитится ходом
-  работы, а передача его пересказывает для вставки в новый заход: рабочее дерево, ветка,
-  сделанное, следующий шаг и особенности захода. В историю она не едет — иначе рядом с ходом
-  работы заводится вторая запись об одном и том же.
 - **Слово для нового понятия ищется в словаре дерева.** Общую часть словаря везёт пакет,
   предметную дописывает дерево надстройкой; словарь уезжает в контекст на запуске сессии
   целиком, поэтому «не читал» основанием не бывает.
@@ -322,21 +207,22 @@ flowchart TD
   это заготовка правки чужого дерева, и часть заготовок отпадает при первом же чтении; уехавшая
   без разбора, она становится работой того, кто её не заказывал. Сводка наблюдений уезжает
   всегда: она говорит, чем пользовались и чем нет, и мнением не является.
-- **Договорённость вливается в спек домена последним коммитом PR.** К этому моменту код
-  написан, привязки известны, и в главной ветке директория `proposed/` не появляется вовсе.
+- **Договорённость вливается в спек домена одним из последних коммитов ветки, до открытия
+  PR.** К этому моменту код написан, привязки известны, и в главной ветке директория
+  `proposed/` не появляется вовсе.
   Готовые к вливанию перечисляет `npm run check:specs`.
 - **Папка закрытой задачи разбирается, а не переносится целиком.** В `docs/archive/` уезжает
   то, что объясняет состоявшееся решение; остальное удаляется. Неразобранную ловит сверка
   очереди работ.
-- **Слияние отбивается, пока ветка везёт папку своей задачи.** Требование стоит на слиянии, а
-  не на открытии PR: до слияния папка ещё нужна — правка по замечаниям разбора идёт в ту
-  же ветку, а без замысла на диске её отбивает гард хода работы. На открытии PR о лежащей
-  папке говорится вслух, и только. Судится содержимое ветки, а не рабочее дерево: снесённая,
-  но не закоммиченная папка въехала бы вместе с веткой.
+- **Открытие PR отбивается, пока ветка везёт папку своей задачи.** Требование стоит здесь, а
+  не на слиянии: слияние нажимает человек на хостинге, где гардов нет вовсе, и его отказ до
+  владельца не доходит. На слиянии та же проверка остаётся вторым рубежом — она ловит слияние,
+  идущее командой. Судится содержимое ветки, а не рабочее дерево: снесённая, но не
+  закоммиченная папка въехала бы вместе с веткой.
 - **Ветка, снёсшая папку, обязана прибавить запись в архив.** Снести дешевле, чем разобрать, и
   первым уходит разбор просьбы — единственная запись слов владельца. Что именно увезено,
   требование не судит: это судит владелец.
-- **Обход — строка `Task-folder-skip: <причина>` в PR или в самой команде слияния.**
+- **Обход — строка `Task-folder-skip: <причина>` в PR или в самой команде.**
   Работа, вливаемая частями, папку до конца не разбирает. Чтение из команды работает и без
   сети: единственный сетевой путь отбивал бы оффлайн то самое слияние, причина которого
   написана в PR. Пустая причина обходом не считается, а сам обход снимает отказ, но не
@@ -386,57 +272,5 @@ flowchart TD
 
 - `task-flow-start` — разведка, разбор, договорённость, замысел, задача и ветка.
 - `task-flow-resume` — возвращение к незаконченной работе новым заходом.
-- `task-flow-close` — вливание договорённости, разбор папки, переезд в архив.
-- `task-flow-handoff` — закрытие захода по заполнению окна: точка остановки и передача.
-
-## Ловушки
-
-- **Папка называется именем ветки, один в один.** Хук запуска ищет её по
-  `git branch --show-current`, и папка, названная иначе, не находится ничем: работа идёт с
-  пустым контекстом, а владельца просят пересказать то, что уже записано.
-- **Разбор просьбы задним числом не переписывается.** Пересказ незаметно подгоняется под уже
-  сделанное, и сверять результат становится не с чем. Решение, изменённое по ходу, дописывается
-  в ход работы, а не правится в разборе.
-- **Договорённость о продукте не кладётся в папку задачи.** Папка умирает с мержем, а
-  договорённость обязана его пережить: её сценарии получают номера в общей нумерации домена,
-  и на них ссылаются заголовки тестов. Обратное тоже верно — ход работы не кладётся в
-  `proposed/`: спек, в котором завелись шаги, снова становится планом и умирает после мержа.
-- **У меню нет строки «вопрос не тот».** Меню годится для выбора значения из закрытого набора;
-  пока постановка вопроса не подтверждена, отвергнуть её владельцу нечем — он выбирает из
-  вариантов, выведенных из неверной посылки. Настройки владельца, требующие меню, требование
-  не снимают: тогда к каждому вопросу добавляется свободный вариант, и он же — единственное
-  место, где вопрос отвергается целиком. Три вопроса ушли одним меню, у одного постановка была
-  ложной, и сказать «вопрос не тот» было нечем. Выбор слова, имени и термина узким вопросом не
-  является никогда.
-- **Субагент вопросов владельцу не задаёт.** Ни роли, ни конвейер до него не достучатся —
-  они возвращают текст главному агенту. Поэтому разбор ведёт главный агент, а роли стоят по
-  обе стороны от него.
-- **Если дефект чинится правкой одного общего числа, спроси владельца, тем ли способом ты его
-  чинишь.** Замер показывает, что дефект ушёл, — но не то, что причину вылечили. В одной
-  задаче так ушли две правки подряд: сначала подняли общее число у соседнего узла, потом
-  перенесли узел в другое место разметки. Обе владелец отверг, а нужный способ назвал сам.
-  Спрашивают до правки, а не показывают замер после.
-- **Путь, предложенный человеку, судится числом его шагов и тем, чем ему для этого надо
-  владеть.** Со стороны кода вариант выглядит дешёвым — «меньше путей», «строку запуска не
-  трогаем», — а человеку он стоит захода на сервер. Однажды рекомендуемым вариантом так стояла
-  выдача токена, за которой владельцу надо было идти по ssh в работающий контейнер; отбивал
-  этот вариант он сам. Цена называется со стороны того, кто пойдёт: сколько шагов и что ему для
-  них нужно. Пересказ действующего порядка без такой оценки владелец читает как одобрение.
-- **Эпик по теме читается до того, как решается раскладка.** Замысел эпика держит решения,
-  которые пережили десяток задач, и разведка по коду их не находит: снятое решение следа в
-  дереве не оставляет. Домен, заведённый генератором и снесённый через полчаса, стоял в замысле
-  прямым запретом — но замысел открыли уже после того, как он был заведён во второй раз.
-- **Работа, которая разбирает чужую папку задачи, разбирает и свою — одним коммитом.** Свою
-  папку она заводит наравне со всеми: исключения из этого требования нет. Круг, которым
-  исключение оправдывали, закрывается не отказом от папки, а порядком разбора: последний
-  коммит снимает обе, и после работы неубранного не остаётся. Однажды такой разбор оставил
-  свою папку, и на неё пришлось заводить третью задачу — лечится это порядком, а не правом
-  работать без замысла на диске. Как разобрать две папки — паттерн `task-flow-close`.
-- **Слово для нового понятия берётся из `docs/GLOSSARY.md` или заводится там же.** Третий файл
-  папки задачи называется `progress.md`, а не `journal.md`, ровно поэтому: журнал в этом
-  дереве один, и он другой.
-- **Черновик папки задачи называется тем же коротким именем, что и будущая ветка.** Команда
-  заведения ищет черновик по нему и, не найдя, молча собирает папку с образца: работа при этом
-  идёт дальше, а разбор просьбы остаётся лежать в брошенном каталоге, и следующий заход
-  расспрашивает владельца заново. Имя черновику дают словами просьбы, а ветке — терминологией
-  договорённости; те же слова, да не те же.
+- `task-flow-close` — снятие черновика, вливание договорённости, приведение текстов.
+- `task-flow-archive` — разбор папки задачи, переезд в описание прошлого, разбор правилами.

package/assets/rules/testing.md

@@ -12,6 +12,9 @@ description: Правило под «Закон о проверяемости».
 применяется. Проверка работающего приложения глазами и замером — правило
 `browser-verification` под тем же законом.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 | В законе                   | Здесь                                                                            |
@@ -167,67 +170,3 @@ flowchart TD
 - `testing-unit` — тест на чистую функцию, на процедуру Connect и разовый тест-доказательство,
   который не коммитится.
 - `testing-e2e` — прогон сквозных тестов, стенд под настоящим nginx, выключатели.
-
-## Ловушки
-
-- **Зелёный `nx test <проект>` не значит, что хоть один файл исполнялся.** Либа без своего
-  `vitest.config.mts` не запускает ничего — так тесты домена броней не запускались ни разу.
-  Либа с конфигом, но без единого `*.spec.ts`, проходит зелёной из-за `passWithNoTests: true`,
-  который обычно стоит в каждом конфиге дерева, и на глаз эти два случая неотличимы: в обоих
-  прогон успешен. Доля либ без единого теста меряется пересчётом ниже — в дереве, где его
-  завели впервые, она вышла почти в две трети. Перед правкой в
-  незнакомой либе проверяется, есть ли в ней хоть один `*.spec.ts`; если нет — первый
-  заводится этой же правкой, а не откладывается: откладывать здесь не с чего, долг уже
-  накоплен. Пересчёт: `for d in $(find libs -name vitest.config.mts -exec dirname {} \;); do
-[ -z "$(find "$d" -name '*.spec.ts')" ] && echo "$d"; done | wc -l`.
-- **Зелёная сводка покрытия не значит, что тесты проходят.** Сверка читает заголовки тестов и
-  сопоставляет их со сценариями спека; исполняется ли тест и чем он кончается — она не знает
-  вовсе, и падающий тест значится в ней покрытием. Три сценария одной панели падали и до правки
-  экрана, а нашлось это только прогоном. Перед правкой экрана его сквозные тесты гоняются один
-  раз до первой строки кода: иначе чужое падение читается как своя регрессия, а своё — как
-  чужое.
-- **«Executable doesn't exist» — состояние машины, а не дефект правки.** Установлен только
-  chromium, `firefox` и `webkit` падают всегда: гонять `--project=chromium`, узкий экран —
-  `--project=mobile-chrome`. Та же ошибка приходит после смены версии Playwright: браузер
-  ставится под конкретную версию, и после подъёма нужен повторный
-  `npx playwright install chromium`. Девять тестов так и упали, и это выглядело регрессией
-  обновления.
-- **Первому прогону сразу после установки браузера верить нельзя.** Два падения сквозного
-  набора не повторились ни при отдельном прогоне тех же тестов, ни при втором полном. Такой
-  прогон повторяют, а выводы делают по второму.
-- Сквозная спека, которой нужен вход, без учётных данных в окружении пропускается молча — в
-  отчёте она значится `skipped`, и прогон выглядит успешным. Имена переменных — при дереве.
-- **Справочник флоу вторых сценариев не заводит.** В `docs/E2E_<ДОМЕН>_FLOWS.md` кладут то,
-  чего в спеке домена нет и быть не должно: `qa-dataid` элементов, состояния разметки, ловушки
-  стенда. Обещанное поведение остаётся сценарием в `scenarios.md`: если списать его во второе
-  место, копии разойдутся молча — `npm run check:specs` этого не увидит.
-- `npx nx serve` проверкой не считается: это шаг из правила `browser-verification`, а не тест.
-- **Кадр, зависящий от загрузки машины, проверяет машину, а не вёрстку.** Ожидание отсчётом
-  времени этим и кончается: на свободной машине набор зелен целиком, на занятой падает, и какой
-  именно кадр не успел — дело случая. Лечится ожиданием события, а не удлинением отсчёта: шрифты
-  подняты, картинки нарисованы, движение остановлено, положение узла не менялось два кадра
-  подряд. Пока ожидание идёт по времени, «проверено снимками» означает «машина была свободна», и
-  перезапуск, давший зелёное, этого не отменяет, а прячет. Восемь кадров расходились с эталоном
-  на 0,15–0,74 % в задании конвейера и проходили на той же машине вне его.
-- **Стенд, поднятый предыдущим шагом, останавливается перед съёмкой.** Оставленный работать, он
-  соревнуется за машину с тем, что снимают, и делает исход прогона зависящим от того, чем занят
-  сосед. Нагрузка, которую задание создаёт себе само — соседняя витрина, только что законченная
-  сборка, — ничем не отличается от чужой.
-- **Свой стенд снимается перед тем, как звать набор.** Прогон переиспользует поднятое на его
-  портах, и стенд, оставленный для замера, отдаёт ему чужую сборку с чужими данными. Красное при
-  этом приходит не строкой про занятый порт, а десятком спек про экраны — то есть выглядит
-  дефектом правки: за один заход так покраснели сначала шесть новых тестов, потом гейт пуша, и
-  оба раза причиной был свой же стенд. Разобранный занятый порт эту сторону не закрывает: он про
-  чужой стенд, а этот — про свой.
-- **Разбор упавшего кадра начинается с чисел, а не с картинки расхождения.** Доля площади
-  говорит, сколько разошлось, и молчит о том, что именно: сдвиг всего кадра на пиксель,
-  переставленные строки и рябь на сглаженных уголках выглядят на картинке одинаково — «стало
-  другим». Читаются координаты разошедшихся точек и величина расхождения по каналу: сдвинутые
-  границы блоков — это раскладка, разошедшийся текст при неподвижных границах — это данные,
-  единица-две по каналу на кривых краях — это цвет. Три расхождения одного набора разобрались
-  ровно так, и ни одно из трёх не оказалось дефектом экрана.
-- **Ожидаемое значение теста не берётся из кода, который тест проверяет.** Вывезенное из
-  проверяемой либы, оно делает тест зелёным при любом значении: «колесо показывает пять строк»
-  сходится и тогда, когда строк стало три. Ожидаемое пишется числом в самой спеке рядом с
-  проверкой, а общий модуль сквозных спек держит приёмы — открыть, дождаться, снять со
-  страницы, — но не то, что от страницы ожидается.