@rt-tools/agent-kit 0.10.0 → 0.12.0

package/assets/rules/spec-driven.md

@@ -11,6 +11,9 @@ description: Правило под «Закон о документации пр
 быть верно про тексты; здесь — из каких слоёв они сложены в этом дереве и что сверяет машина.
 Формулировки — правило `doc-style` под тем же законом.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 ```
@@ -21,6 +24,7 @@ description: Правило под «Закон о документации пр
   ├─ ПРАВИЛО    .claude/skills/<правило>/SKILL.md   (kind: rule, law: <закон>)
   │             привязывает закон к этому проекту; несколько правил на закон
   │             .claude/skills/<правило>/implementation.md — привязка к коду
+  │             .claude/skills/<правило>/pitfalls.md — холодная часть: грузится по требованию
   │
   │  └─ ПАТТЕРН  .claude/skills/<правило>-<что>/SKILL.md   (kind: pattern, rule: <правило>)
   │              готовый код и конкретные приёмы; минимум один на правило
@@ -125,6 +129,13 @@ flowchart TD
 - **Слоёв законов два, а имя закона одно на оба.** Общий лежит в корне конституции, закон
   приложения — в `application/`; ни `law:`, ни `**Законы:**` слоя не называют, поэтому имена
   законов уникальны по всему дереву конституции.
+- **У правила бывает третий файл, и в него уходит то, что при решении не читают.** Ловушки и
+  поведение по разборам происшествий нужны не тому, кто принимает обычное решение, а тому, кто
+  разбирает промах или спорит с гардом, — а грузятся они вместе с правилом каждый раз и растут
+  быстрее статей. Такой текст уезжает в `pitfalls.md` рядом, правило называет его строкой в
+  шапке, и грузится он по требованию. Отказ гейта о холодной части молчит: он зовёт правило, а о
+  третьем файле говорит само правило.
+
 - **Спек объявляет законы, которые применяет, и связь сверяется в обе стороны.** Закон,
   названный в тексте спека, обязан стоять в шапке: иначе по закону не узнать, какие домены
   на нём стоят.
@@ -134,6 +145,28 @@ flowchart TD
   про дерево, где того гарда не разложили; поправить это дерево не может ничем, если у ресурса
   нет надстройки. Требование ресурса к ресурсу при этом объявляется строкой в шапке, а не
   выводится из такой фразы.
+- **Статья правила говорит о своей применимости сама, строкой признака при себе.** Отказ гейта
+  зовёт правило целиком, а под конкретную правку подпадает одна его статья: платить за решение
+  полной ценой правила — значит учить не читать лишнего, то есть работать хуже разведанным.
+  Признак стоит при статье, а не в карте гейта: карта знает путь и правило, но не знает, какая
+  из двух десятков статей про этот путь.
+
+    ```markdown
+    - **Заголовок статьи.** Текст статьи, как обычно.
+      <!-- rt-when: *.scss *.css -->
+    ```
+
+    Образцы разделены пробелом и сверяются с путём правки как образцы оболочки, а не поиском по
+    словам: поиск называет не ту статью и молчит об этом. Образец без каталога сверяется и с
+    именем файла. Комментарий не виден в собранной разметке, поэтому статья читается человеком
+    как прежде.
+
+- **Статья без признака законна, и правило без единого признака — тоже.** Признак ставится тем
+  статьям, чьё правило отбивает на правке файла; остальные размечаются по мере того, как их
+  отбития попадут в сводку. Отсутствие признака означает «эту статью по пути правки не
+  выбирают», а не промах: требовать его у всех значило бы размечать наугад те правила, которые
+  ни разу никого не отбили.
+
 - **Паттерн находится по полю `rule:`, а не по приставке имени.** Приставку имени несут не все
   паттерны, и поиск по имени правила таких не видит: сверка ищет их полем, человек — разделом
   «Паттерны» самого правила. Счёт паттернов, собранный приставками, выходит меньше настоящего, а
@@ -161,6 +194,12 @@ flowchart TD
 доменов раньше, чем код научился в него приходить, и всё это время читалось описанием
 работающего.
 
+Полноту разметки статей признаком применимости не считает ничто. Правило, у которого признака
+нет ни у одной статьи, отбивает прежним текстом — и от размеченного отличается только тем, что
+исполнитель читает его целиком; ни одна проверка об этом не говорит. Судит это сводка
+наблюдений: правило, которое чаще прочего отбивает на правке файла, и есть первое, что
+размечают.
+
 Полноту разделов у самого закона, правила и паттерна здесь не проверяет ничто. Статьи о том,
 что текст судится не слабее своей копии, что невыбранная редакция судится наравне с выбранной и
 что набор разделов объявлен отдельно от образца, исполняются там, где эти тексты пишут, — в
@@ -172,33 +211,3 @@ flowchart TD
 
 - `spec-driven-domain` — заведение и правка спека домена, сценарии, привязка.
 - `spec-driven-rule` — заведение закона, правила и паттерна.
-
-## Ловушки
-
-- **`tasks.md` в спеке не заводить.** Шаги — артефакт сессии, им место в ветке или в описании
-  PR. Как только в директории появляются «шаги», спек снова становится планом и умирает после
-  мержа.
-- **Спек описывает установившееся, а не предстоящее.** Единственное место, где он говорит о
-  будущем, — `proposed/<фича>/`. После выкатки его текст вливается в спек домена, директория
-  удаляется, идентификаторы сценариев не меняются.
-- **Семантику полей не сверяет ничто.** Проверка знает имена процедур, коды отказа и связь
-  сценариев с тестами; что означает пустое поле — не знает. Правка `.proto` поэтому тянет
-  спеки всех доменов, чьи процедуры она задела, в той же ветке.
-- **Живость символа считается совпадением имени по всему дереву, а не вызовом.** Символу
-  хватает второго упоминания где угодно — в чужом поле с тем же именем, в атрибуте разметки.
-  Место, где правило исполняется на самом деле, подтверждается только чтением кода.
-- **Якорь в `tools/*.mjs` сверяется почти ничем:** живость считается только для `.ts`, а
-  исходники обходятся по `apps`, `libs` и `prisma`. Правило, привязанное к проверке, поэтому
-  читается вместе с её телом.
-- **Зелёная проверка не значит, что структура верна.** Спутники с привязкой сначала лежали
-  рядом с законами, и проверка была зелёной именно потому, что структура совпадала с тем,
-  чего проверка сама и ждала.
-- **Конфликт мержа в спеке разрешается сохранением обеих сторон, а не выбором одной.** Две
-  ветки дописывают в конец одних и тех же списков — сценариев, правил, строк привязки, — и
-  обе стороны верны: конфликт здесь не спор, а две дописи в одно место. Номера сценариев при
-  разрешении не пересчитываются: идентификатор — ключ связи с тестами, и сдвиг номеров рвёт
-  сверку у соседей, которых правка не касалась. Порядок сохранённых сторон держится
-  одинаковым в `spec.md`, `scenarios.md` и `implementation.md`: иначе правило, его сценарий и
-  его привязка перестают находиться друг по другу. После разрешения гоняется
-  `npm run check:specs` — конфликт в спеке кода не задевает, и ни сборка, ни линтеры его не
-  увидят.

package/assets/rules/styling-bem.md

@@ -12,6 +12,9 @@ description: Правило под «Закон о фронтовом прило
 `component-structure`, состояние — `angular-patterns`, окружение браузера —
 `platform-access`, слой обращения к серверу — `api-layer`. Все пять под одним законом.
 
+**Холодная часть:** `pitfalls.md` рядом — ловушки, грабли, на которые уже наступали.
+Грузится по требованию, а не вместе с правилом.
+
 ## Как это называется здесь
 
 | В законе                        | Здесь                                                                                                                                        |
@@ -51,28 +54,45 @@ flowchart TD
 - **Оформление берётся токеном `--rt-*`, а не пишется значением на месте.** Составные
   значения — `box-shadow`, `text-shadow` — берутся готовым токеном целиком, а не собираются
   из частей.
+  <!-- rt-when: *.scss *.css -->
+
 - **У каждого класса элемента есть своё правило стилей.** Класс без правила выглядит рабочим
   и молча ничего не делает.
+  <!-- rt-when: *.scss *.css -->
+
 - **Класс ставится директивой, а не строкой в атрибуте.** Имя блока `rtElem` получает
   инъекцией от ближайшего предка с `rtBlock`, и повторить этот разбор по тексту шаблона нечем.
+  <!-- rt-when: *.html *.scss -->
+
 - **Раскладка объявлена в общем слое приложения, а не в стилях экрана.** У компонента экрана
   вне кита файл стилей по умолчанию пустой.
+  <!-- rt-when: *.scss *.css -->
+
 - **Шторку и окно открывает служба кита, а не номер слоя.** Числа шкалы сравниваются только
   между соседями по разметке; служба выносит разметку наружу, к `<body>`, и сравнивать её
   становится не с чем.
+  <!-- rt-when: *.ts *.scss -->
+
 - **Номер слоя берётся из шкалы, а не пишется числом в файле компонента.** Шкала — единственное
   место, где слои видно рядом: написанное на месте число в неё не попадает, и следующий узел
   занимает тот же номер, ничего об этом не узнав.
+  <!-- rt-when: *.scss *.css -->
+
 - **Размер элемента управления выбирается по признаку указателя, а не по ширине экрана.**
   Планшет в ландшафте шире порога узкого вьюпорта, а нажимают по нему пальцем: `pointer: coarse`
   отвечает про способ нажатия, ширина — про место под раскладку. Ступени берутся у кита, а не
   назначаются пикселями.
+  <!-- rt-when: *.scss *.css -->
+
 - **Файл стилей не длиннее 500 строк.** Предел общий с кодом и текстами, но stylelint длину не
   судит вовсе — держит его проверка дерева. Выросший файл экрана делится по блокам, а общая
   раскладка уходит в свой слой.
+  <!-- rt-when: *.scss *.css -->
+
 - **Предупреждение stylelint роняет прогон наравне с ошибкой.** `!important` объявлен
   предупреждением, а прогон идёт с `--max-warnings 0`: иначе запрет читается как пожелание —
   два таких предупреждения лежали в дереве, а `npm run stylelint` возвращал ноль и гейтом не был.
+  <!-- rt-when: *.scss *.css -->
 
 ## Чего из закона здесь нет
 
@@ -85,42 +105,3 @@ flowchart TD
 - `styling-bem-layout` — экран на общем слое раскладки, блоки приложения.
 - `styling-bem-component` — стили компонента кита, `:host`, модификаторы, язык оформления сайта.
 - `styling-bem-sheet` — шторка и окно поверх страницы: чем открываются, подложка, замер.
-
-## Ловушки
-
-- **`rtElem` без предка с `rtBlock` роняет отрисовку в рантайме** — сборка и линт молчат.
-- **Спроецированный узел блока-предка не имеет.** `rtElem` берёт имя блока инъекцией от
-  ближайшего предка **по месту объявления шаблона**, а не по месту вставки: элемент, который
-  экран объявляет у себя и отдаёт в проекцию чужого компонента, ищет `rtBlock` в своём шаблоне
-  и не находит. Отрисовка падает в рантайме, сборка и линт зелёные. Класс на такой узел
-  вешается правилом по селектору кита в общем слое раскладки, а не директивой.
-- **Элемент с `backdrop-filter` или своим `z-index` замыкает потомков в свой слой.** Липкая
-  шапка с размытием — самый частый случай: номер слоя у того, что лежит внутри неё,
-  сравнивается не с соседями по странице, а только с соседями внутри шапки, и нижняя панель
-  накрывает открытую шторку вместе с её кнопкой. Проверяется это `elementFromPoint` в центре
-  кнопки: сборка, линт и скриншот показывают тут целую страницу.
-- **До узла, вынесенного к `<body>`, стили компонента не достают.** Превью и заглушку переноса
-  кладёт туда библиотека, а правила компонента заскоуплены атрибутом: файл выглядит рабочим и
-  не красит ничего. Такие правила объявляются в общем слое приложения. Ни сборка, ни линт, ни
-  проверка «класс без правила» этого не видят: класса такого в шаблоне нет вовсе, и пролежать
-  это может несколько задач подряд.
-- **Имя токена не сверяется ничем.** Ссылка на несуществующий токен собирается, проходит
-  stylelint и проверку класса без правила, а свойство молча берёт наследованное значение:
-  правило выглядит написанным и не красит ничего. Ловится это только замером в браузере, а
-  имена берутся из объявлений кита, а не по догадке о том, как токен должен был бы называться.
-- **`rtBlock` на `<ng-container>` класса не ставит вовсе:** узел это комментарий, и имя блока
-  он только объявляет потомкам. Класс блока экрана вешает хост через `host: { class: … }`.
-- **`justify-content: center` во flex-контейнере с `overflow-x` уводит первые элементы за
-  нулевой скролл** — доскроллить до них невозможно. В прокручиваемых лентах —
-  `justify-content: safe center`.
-- **`scrollbar-gutter: stable` на корне не заводить:** резерв под полосу прокрутки сужает
-  содержащий блок для `position: fixed`, и попап, выровненный по правому краю, встаёт на
-  ширину резерва левее своей кнопки.
-- **`& + :host` невалиден:** изнутри компонента до соседнего хоста не дотянуться. Разделитель
-  между повторяющимися хостами — `:host(:not(:first-of-type))`.
-- **`[attr.aria-disabled]` визуального состояния не даёт:** браузер стилизует `:disabled`, но
-  атрибуты `aria-*` — нет. К каждому `aria-disabled` заводится правило `[aria-disabled='true']`.
-- **Гарнитуру с `body` элементы формы не наследуют:** браузер задаёт `button`, `input`,
-  `select` и `textarea` свой шрифт. Наследование включено глобально — сбрасывать его нельзя.
-- **Комментарии-выключатели stylelint не ставятся.** Селекторы объединяются вложенностью.
-- **При переносе стилей новых объявлений не появляется** — только перемещение существующих.

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
-- **Состояние:** `этап-идёт`
-```
+Состояние объявляется в разделе «Где стоим» хода работы машиночитаемой строкой
+``- **Состояние:** `этап-идёт` `` и перезаписывается вместе с ним.
 
 | Состояние                 | Вход в него                                     | Обязательное действие                                  | Ведёт паттерн      |
 | ------------------------- | ----------------------------------------------- | ------------------------------------------------------ | ------------------ |
@@ -58,41 +58,20 @@ description: Правило под «Закон о ведении работы»
 | `этапы-кончились`         | все этапы отмечены                              | прогнать набор и открыть PR черновиком                 | `task-flow-close`  |
 | `работа-отдана`           | PR открыт черновиком                            | взять следующую задачу                                 | `task-flow-resume` |
 | `разбор-кончился`         | прогон зелёный, замечаний нет                   | влить договорённость, привести тексты, разобрать папку | `task-flow-close`  |
-| `папка-разобрана`         | папки в ветке нет, запись в архиве есть         | снять черновик и попросить влить                       | `task-flow-close`  |
-| `влито`                   | PR слит человеком                               | разбор работы правилами и сверка очереди               | `task-flow-close`  |
+| `папка-разобрана`         | папки в ветке нет, запись в архиве есть         | снять черновик и попросить влить                       | `task-flow-archive` |
+| `влито`                   | PR слит человеком                               | разбор работы правилами и сверка очереди               | `task-flow-archive` |
 
 Ни у одного состояния обязательное действие не звучит как «ждать»: ожидание чужого шага
-состоянием работы не является. Прогон, разбор владельцем и слияние идут без исполнителя, и от
-взгляда быстрее не становятся — поэтому в `работа-отдана` обязательное действие смотрит на
-следующую задачу, а не на открытый PR.
-
-Заполнение окна захода состоянием работы тоже не бывает: заход кончается передачей, работа
-остаётся в том состоянии, в каком стояла, а следующий заход читает строку и продолжает с неё.
-Ведёт закрытие захода паттерн `task-flow-handoff`.
+состоянием работы не является — прогон, разбор владельцем и слияние идут без исполнителя и от
+взгляда быстрее не становятся, поэтому в `работа-отдана` обязательное действие смотрит на
+следующую задачу, а не на открытый PR. Заполнение окна захода состоянием тоже не бывает: заход
+кончается передачей, работа остаётся в том состоянии, в каком стояла, а следующий заход читает
+строку и продолжает с неё. Чем ход кончается и что его концом не бывает — правило
+`turn-conduct` под тем же законом.
 
 Перечень показывается владельцу в начале работы, и на нём же отмечается, где стоим: иначе после
 шести вопросов не видно ни того, что будет дальше, ни сколько всего впереди.
 
-## Выходы хода
-
-Ход кончается четырьмя способами, и других нет:
-
-| Выход                                              | Чем подтверждается                                              |
-| -------------------------------------------------- | --------------------------------------------------------------- |
-| вопрос владельцу, ответа на который в правилах нет | вопрос задан, и за тот же ход правила читались                  |
-| отказ гарда                                        | отказ назван владельцу, обход не искался                        |
-| заполненное окно захода                            | ход работы дописан, передача написана                           |
-| работа отдана, и следующая начата                  | PR открыт, и по следующей задаче сделано действие, а не сказано |
-
-Всё остальное — продолжение хода, а не его конец. Веха ходом не кончается: ни коммит, ни
-прочитанная договорённость, ни граница «прочитал — сейчас правлю», ни зелёная проверка. Слова
-«иду дальше» и «работаю дальше» владелец читает как совершающееся действие, и писать их вместо
-результата нельзя.
-
-Три способа кончить ход выглядят работой и ею не являются: сводка о чужом шаге, меню при
-назначенном порядке и объявление намерения. Что при этом должно быть верно — ниже, в статьях
-о применении закона.
-
 ## Ход
 
 Ход работы от просьбы владельца до закрытия: где стоит разбор, что требует гард и куда девается
@@ -175,104 +154,8 @@ flowchart TD
   правку кода приложения, и работа, которая туда не доходит, проходит мимо него — но папку
   заводит всё равно: статья правила говорит «под любую работу, без исключений». Прочитанный
   как признак, гард становится разрешением работать без замысла везде, куда он не смотрит.
-- **Сводка о чужом шаге.** Прогон, разбор владельцем и слияние идут без исполнителя и от взгляда
-  быстрее не становятся. Ход, кончившийся такой сводкой, владелец читает как работу: она полна,
-  в ней названы номера и состояния, и пустоты за ней не видно. О чужом шаге говорят вместе с
-  начатым своим, а не вместо него. За один заход это было нарушено четырежды, и готовая работа
-  простояла в невлитом PR почти три часа.
-- **Меню при назначенном порядке.** Выбор, предложенный владельцу, пока эпик не кончился, — это
-  просьба назначить порядок заново. Работы в эпике не осталось — так и говорится: эпик
-  кончился, — а не «чем займёмся».
-- **Объявление намерения.** «Беру следующую задачу» — не то же самое, что взять её: фраза живёт
-  до конца хода, а работа не двигается. Названо может быть только сделанное: номер заведённой
-  задачи, имя заведённой ветки, переведённая колонка.
-
-- **Прерывание работы владельцем называется вслух.** Пришло задание, останавливающее начатое, —
-  исполнитель говорит, что стоит, на чём остановлено и что будет с прежней работой, и только
-  потом берётся за новое. Молчание об этом владелец читает как «прежнее кончилось».
-- **Остановка называется отдельной репликой.** Не строкой в конце отчёта: там она тонет —
-  владелец читает отчёт как рассказ о сделанном. Называются три вещи: что стоит, чего оно ждёт
-  и что владелец может решить.
-- **Выходы хода стережёт страж, а не память исполнителя.** Он читает объявленное состояние
-  работы и то, что за ход по ней сделано: правку файла или команду, меняющую дерево. Ход, в
-  котором не было ни того ни другого, возвращается исполнителю вместе со следующим шагом из
-  хода работы. Отданную и влитую работу страж не судит: она уже дождалась чужого шага.
-- **Этап замысла объявляется закрытым только после того, как его команда проверки прошла.**
-  Строка «Чем проверяется» несёт команду обратными кавычками и то, что в её выводе означает
-  «сошлось». Страж читает прежний номер этапа из истории ветки и не выпускает ход, в котором
-  номер вырос, а команда не запускалась: через заход отмеченное по памяти неотличимо от
-  проверенного.
-- **Слово об остановке страж читает у владельца, а не у исполнителя.** Иначе остановку
-  объявляет тот, кому она в эту минуту удобна, и запрет держится ровно до первого неудобства.
-- **Утверждение о состоянии дерева стережёт гард утверждения, а не память исполнителя.** Всё,
-  что ответ владельцу говорит о дереве, несёт команду и её вывод: сказанное без команды
-  утверждением не считается — ни «проверено», ни «снято», ни «готово». Гард читает текст,
-  сказанный владельцу за ход, и ищет команду того же хода; у каждого слова назван свой род
-  команды, потому что общий признак «команда была» подтверждал бы одно другим. Прошлый ход не
-  годится: состояние дерева меняется, и вчерашний вывод о нынешнем молчит. Восемь разборов
-  подряд пришлись на этот промах, и каждый раз в правило дописывалась ещё одна статья —
-  держит его теперь машина.
-- **Слово-утверждение гард ловит, неверный вывод — нет.** Об образце, судимом по одному его
-  файлу, и о пути, которым человек не пойдёт, судить нечем: там нет ни слова, ни команды, с
-  которой сверять. Это известная граница гарда, и держат её статьи ниже, а не он.
-- **Ход о чужом шаге стережёт гард ожидания, а не память исполнителя.** Он отбивает завершение
-  хода, в котором о чужом шаге сказано, а по следующей задаче не сделано ни одного действия —
-  ни заведения задачи, ни ветки, ни папки, ни перевода колонки. Чужой шаг он узнаёт по двум
-  признакам: в ходе открыт PR либо в ходе прочитан красный прогон. Оба берутся из самого хода:
-  спросить хостинг было бы точнее, но сетевой вызов на завершении хода падает вместе со связью
-  и отбивал бы работу вместо промаха, а вывод команды о прогоне в записи хода уже лежит. Слова
-  «беру следующую задачу» гард действием не считает — ровно потому, что их и произносят вместо
-  неё.
-- **Конец прогона узнаётся возвратом фоновой команды, а не взглядом на страницу.** Ожидание,
-  запущенное в фоне отдельным ходом, возвращает исполнителя к PR само; до тех пор ход занят
-  следующей задачей. Взгляд на страницу этого не даёт: он либо повторяется вхолостую, либо не
-  повторяется вовсе, и оба исхода со стороны выглядят одинаково — работа не двигается.
-- **Отказ гарда кончает ход.** Другого пути к отбитой правке не ищут: ни командой оболочки, ни
-  соседним инструментом, ни правкой самого гарда. Отбитая правка либо делается после того, как
-  условие отказа выполнено, либо не делается вовсе — и тогда владельцу называется отказ, а не
-  результат. Обход стоит дороже отказа: гард отбивает один файл, а обойдённый гард снимает
-  требование со всего дерева и молчит об этом. Держится это не только памятью — гарды судят и
-  команду оболочки, которая пишет файл.
-- **Ход, в котором владельцу задан вопрос, не заканчивается, пока за этот же ход не читались
-  законы и правила.** Чтением считается любой из трёх путей: загрузка правила, чтение файла
-  законов или правил, поиск по ним. Отбивает гард разговора — на завершении хода, а не на
-  инструменте вопроса: спрашивают чаще прозой, чем меню. Найденное ложится в раздел «Что уже
-  сказано в правилах» разбора.
-- **Действия, которые исполнитель не делает без слова владельца, перечислены в компаньоне
-  правила.** Список у каждого дерева свой — пакет знает только требование, чтобы список был
-  назван. Не названный, он выводится из общих слов, и «делай, что нужно по плану» становится
-  разрешением на пуш и правку общих документов заодно с коммитом. Оценка «это безопасно» списка
-  не заменяет: её назначает тот, кому она в эту минуту удобна, и она плывёт. За один заход одна
-  и та же команда была сначала слишком опасной, чтобы её позвать, а через два хода —
-  достаточно безопасной, чтобы позвать без спроса.
-- **У отказа от необратимого действия есть безопасная часть, и она делается.** Требование
-  спросить владельца относится к действию, а не к ходу: работа, у которой отделима часть без
-  последствий, делится, а не откладывается целиком. Список вариантов, поданный вместо работы,
-  читается как работа — тем полнее, чем аккуратнее он составлен: он пронумерован, в нём названы
-  цифры, и именно поэтому пустота хода за ним не видна. Владельцу называется, что уже сделано и
-  что осталось за его словом, — а не выбор из вариантов вместо и того и другого.
-- **Ход, в котором исполнитель признал промах, не заканчивается, пока записи о происшествии
-  нет.** Отбивает гард происшествия — на завершении хода: к моменту признания промах уже
-  случился, и ловить раньше нечего. Признание ловится набором образцов, а не пониманием смысла;
-  промах, признанный словами вне набора, гард пропускает, и это его известная граница, а не
-  обещание.
-- **Заход, начатый с передачи, входит в работу тем же правилом, что и всякий другой.** Передача
-  лежит вне дерева, её не читает ни одна проверка, и написана она вчера: всё, что в ней стоит,
-  проверяется деревом. Порядок входа — четыре шага в паттерне возвращения; стережёт его гард, а
-  не память: порядок, записанный только словами, исполняется, пока о нём помнят.
-- **Состояние незаконченной работы приходит в контекст на запуске сессии.** Замысел и ход
-  работы отдаются целиком, разбор просьбы — путём. Ветка вида `<КЛЮЧ>-*` без папки даёт
-  предупреждение с готовой командой, но сессию не рвёт.
 - **Сделанное отмечается только в ходе работы.** «Где стоим» перезаписывается каждым заходом,
   а не дописывается: это первое, что читает следующий заход.
-- **Заполнение окна захода стережёт гард, а не память исполнителя.** На первом пороге он
-  напоминает выбирать точку остановки, на втором отбивает всё, кроме записи хода работы,
-  передачи и команд поставки. Размер окна и оба порога дерево задаёт само; не задавшее размера
-  стража не получает.
-- **Заход закрывается передачей, которая лежит вне дерева.** Состояние работы коммитится ходом
-  работы, а передача его пересказывает для вставки в новый заход: рабочее дерево, ветка,
-  сделанное, следующий шаг и особенности захода. В историю она не едет — иначе рядом с ходом
-  работы заводится вторая запись об одном и том же.
 - **Слово для нового понятия ищется в словаре дерева.** Общую часть словаря везёт пакет,
   предметную дописывает дерево надстройкой; словарь уезжает в контекст на запуске сессии
   целиком, поэтому «не читал» основанием не бывает.
@@ -373,57 +256,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 % в задании конвейера и проходили на той же машине вне его.
-- **Стенд, поднятый предыдущим шагом, останавливается перед съёмкой.** Оставленный работать, он
-  соревнуется за машину с тем, что снимают, и делает исход прогона зависящим от того, чем занят
-  сосед. Нагрузка, которую задание создаёт себе само — соседняя витрина, только что законченная
-  сборка, — ничем не отличается от чужой.
-- **Свой стенд снимается перед тем, как звать набор.** Прогон переиспользует поднятое на его
-  портах, и стенд, оставленный для замера, отдаёт ему чужую сборку с чужими данными. Красное при
-  этом приходит не строкой про занятый порт, а десятком спек про экраны — то есть выглядит
-  дефектом правки: за один заход так покраснели сначала шесть новых тестов, потом гейт пуша, и
-  оба раза причиной был свой же стенд. Разобранный занятый порт эту сторону не закрывает: он про
-  чужой стенд, а этот — про свой.
-- **Разбор упавшего кадра начинается с чисел, а не с картинки расхождения.** Доля площади
-  говорит, сколько разошлось, и молчит о том, что именно: сдвиг всего кадра на пиксель,
-  переставленные строки и рябь на сглаженных уголках выглядят на картинке одинаково — «стало
-  другим». Читаются координаты разошедшихся точек и величина расхождения по каналу: сдвинутые
-  границы блоков — это раскладка, разошедшийся текст при неподвижных границах — это данные,
-  единица-две по каналу на кривых краях — это цвет. Три расхождения одного набора разобрались
-  ровно так, и ни одно из трёх не оказалось дефектом экрана.
-- **Ожидаемое значение теста не берётся из кода, который тест проверяет.** Вывезенное из
-  проверяемой либы, оно делает тест зелёным при любом значении: «колесо показывает пять строк»
-  сходится и тогда, когда строк стало три. Ожидаемое пишется числом в самой спеке рядом с
-  проверкой, а общий модуль сквозных спек держит приёмы — открыть, дождаться, снять со
-  страницы, — но не то, что от страницы ожидается.