@rt-tools/agent-kit 0.10.0 → 0.12.0

package/assets/patterns/turn-entry-map.md

@@ -0,0 +1,81 @@
+---
+name: turn-entry-map
+kind: pattern
+rule: turn-entry
+description: Паттерн правила turn-entry. Брать при правке карты хода и хука, который её подаёт, — что в карту входит, чем она отличается от правила, как хук молчит о недостающем и как это проверяется. Не брать для формы самой передачи — это паттерн task-flow-handoff.
+---
+
+# Карта хода и её подача — готовый код
+
+Паттерн правила `turn-entry`. Что при этом должно быть верно — закон
+`docs/constitution/work-conduct.md`.
+
+## Когда брать
+
+- В правило ведения работы добавили состояние — карта отстала.
+- Правится хук входа или порядок, в котором части входа кладутся в контекст.
+- Проверка карты покраснела.
+
+## Что входит в карту, а что нет
+
+Карта отвечает на вопрос «что делать», правило — на вопрос «почему». Признак отбора один: строка,
+которую заход прочитает и после которой сделает следующий шаг, — в карту; строка, которая
+объясняет, откуда требование взялось, — в правило.
+
+| В карту                                        | В правило                                          |
+| ---------------------------------------------- | -------------------------------------------------- |
+| имя состояния и его обязательное действие      | почему это действие обязательно                    |
+| паттерн, который состояние ведёт               | разбор происшествия, из которого оно выросло       |
+| четыре выхода хода и чем каждый подтверждается | что бывает, когда ход кончают иначе                |
+| строка о том, что остальное — продолжение хода | перечень того, чем ход кончать нельзя, с примерами |
+
+Разбор происшествия в карту не переезжает никогда: он объясняет, а объяснение — это правило.
+
+## Подача: сперва передача, потом карта
+
+Порядок не безразличен. Передача говорит, где именно стоит эта работа, карта — что делают в
+таком месте вообще. Прочитанная первой, карта отвечает на вопрос, которого заход ещё не задал.
+
+```bash
+# передача — по имени текущей ветки, не выбором из каталога
+handoff="$ROOT/${RT_HANDOFF_DIR:-.claude/handoff}/$(git branch --show-current).md"
+[ -r "$handoff" ] && { printf 'ПЕРЕДАЧА ПРОШЛОГО ЗАХОДА\n\n'; cat "$handoff"; }
+
+# карта — своим файлом, а не разбором правила
+[ -r "$map" ] && { printf 'КАРТА ХОДА\n\n'; cat "$map"; }
+
+exit 0
+```
+
+Три вещи в этом куске обязательны и легко теряются:
+
+- **`-r`, а не `-f`.** Файл может существовать и не читаться; `-f` тогда пропускает `cat`
+  дальше, и хук печатает заголовок над пустотой.
+- **`exit 0` в конце и никаких других выходов.** Хук входа ничего не отбивает: заход без части
+  контекста лучше, чем отбитый запуск.
+- **Имя файла собирается из ветки.** Выбор «первого попавшегося» в каталоге подаёт чужую
+  передачу, и выглядит она как своя.
+
+## Чем это проверяется
+
+```bash
+node tools/check-turn-map.mjs   # размер, полнота состояний в обе стороны, четыре выхода
+```
+
+Проверка сверяет имена состояний карты с таблицей правила в обе стороны: состояние, заведённое
+правилом и забытое в карте, и состояние, оставшееся в карте после переименования, — оба
+расхождения.
+
+Живая проба хука делается на дереве, где обе части лежат, и повторяется четырежды: обе части,
+без передачи, без карты, без обеих. Последний случай обязан дать пустой вывод и нулевой код —
+хук, промолчавший с ненулевым кодом, читается как отбитый запуск.
+
+## Ловушки
+
+- **Предел размера назначается замером, а не на глаз.** Первое число выбрали «вдвое больше
+  нынешней карты» — и проверка покраснела на собственном тексте в первом же прогоне: карта в
+  кириллице весит вдвое больше, чем кажется по числу строк.
+- **Выход за предел означает деление карты, а не подъём предела.** Поднятый однажды, он
+  поднимается и во второй раз, и карта тихо становится вторым экземпляром правила.
+- **Карта, разобранная из правила на месте, ломается молча.** Правку разметки таблицы не видит
+  ни одна проверка, а карта после неё приходит пустой — и заход об этом не узнает.

package/assets/pitfalls/doc-style.md

@@ -0,0 +1,80 @@
+# Тексты проекта — холодная часть
+
+Ловушки: грабли, на которые уже наступали. Грузится не вместе с правилом, а по
+требованию — при обычном решении она не нужна.
+
+Правило — `doc-style`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Оставшаяся работа не записывается в документ, а заводится задачей.** `docs/BACKLOG.md`
+  держит только то, что задачей не бывает: договорённости и решения, которые решено не
+  править. Признак — утверждение остаётся, если править его никто не собирается. «Сделать
+  потом» в плане, README или спеке — второй список работ: он расходится с бордой молча, а
+  разбирать его потом дороже, чем завести задачу сразу. Из 1411 строк документа действующими
+  оказались 71, и на разбор остальных ушла отдельная задача. Как разбирать накопившееся —
+  паттерн `doc-style-sweep`.
+- **Словарь действует и на разговор с владельцем, не только на файлы.** Он приходит в контекст
+  на запуске сессии, поэтому «не читал» основанием не бывает. Слово из левой колонки «Так не
+  пишем» всплывало именно в ответах: в дереве его уже вычистили, а в PR о сделанном оно
+  оставалось, и владелец читал ровно то слово, от которого отказались.
+- **Термин берётся из `docs/GLOSSARY.md`, а не придумывается на месте.** Слова, которого там
+  нет, у читателя нет тоже: «журнал приложения» простоял в спеке почты, пока владелец не
+  спросил, что это, — оказалось, логи бэкенда, а слово «журнал» здесь уже занято журналом
+  событий. Новое слово либо заводится в словаре вместе с правкой, либо заменяется тем, что
+  уже есть.
+- **Проход по словарю глазами слово не находит.** «Формулировки приведены к словарю» означает
+  ровно те строки, которые в тот момент читали: «спека» пережила такой проход и осталась в
+  соседней строке того же файла. Слово из левой колонки таблицы «Так не пишем» вычищается
+  грепом по всему дереву, а не вычиткой. Форма задаётся точно: «спек» — документ — склоняется
+  в «спека» и «спеки» тоже, и совпадений по корню законных больше, чем нарушений; ищутся
+  сочетания («спеки на … нет», «спека проверяет»), а не корень.
+- **Снятое имя вычищается одним грепом по всему дереву:** правила, их зеркала в скилах,
+  документы и комментарии. Описание того, чего в коде уже нет, читается как действующее
+  указание.
+- **У снятого слова второе значение возвращается после сплошной замены, а не обходится до
+  неё.** Слово снимают ровно потому, что оно стояло над двумя вещами, и второе значение при
+  этом остаётся законным. Отобрать его заранее нечем: какое из двух значений в строке, видно
+  только по соседнему тексту, а строк бывают сотни. Порядок обратный — сплошная замена, затем
+  сплошной просмотр самой правки, и найденное второе значение возвращается поимённо. Из 353
+  замен так вернулись шесть, и две первые были поломкой: сверка печатала новое имя дважды
+  подряд, а комментарий обещал «поломку вместо PR о том, что долгов нет». Просматривается
+  правка, а не дерево после неё: в дереве обе стороны выглядят одинаково верными.
+- **Поиск по дереву не покрывает того, что уже уехало наружу.** Заголовок задачи и её тело,
+  заголовок PR и его тело, заголовки коммитов лежат вне файлов, и проверки текстов их не
+  читают вовсе. Вычистив слово в дереве, обходят те же места в очереди работ и в истории:
+
+    ```bash
+    <клиент хостинга> api "<путь к PR>" --jq '.title, .body' | grep -i '<слово>'
+    <клиент хостинга> api "<путь к задаче>" --jq '.title, .body' | grep -i '<слово>'
+    git log --format='%s%n%b' <база>..HEAD | grep -i '<слово>'
+    ```
+
+    Заголовок PR правится вызовом хостинга, заголовок коммита — только переписыванием ветки,
+    поэтому его проверяют до пуша. Выдуманное слово было вычищено из трёх файлов и объявлено
+    снятым, а в заголовке PR и в заголовке коммита осталось — владелец прочитал именно его.
+
+- **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет
+  внутри одной ветки: «шестнадцать пар» стало неправдой через два коммита после того, как
+  было написано, и нашёл это владелец, а не проверка. Число, которое придётся пересчитывать
+  при каждой правке, лучше не писать вовсе. Число, полученное разбором текста, сверяется на
+  выборке руками до того, как его называют: разбор, не знающий второй формы записи, ошибается
+  молча — «51 пункт без задачи» оказался шестью, потому что номер стоял и отдельной строкой, и
+  в заголовке подраздела.
+- **Названная в тексте проверка запускается, а не пересказывается.** «Проверка есть» и
+  «проверка проходит» — разные утверждения, и второго в тексте обычно нет вовсе. Из четырёх
+  проверок, названных правилом, три оказались не в том состоянии, в каком текст их описывает:
+  одна отдавала полтора десятка замечаний, вторая переписывала файлы самим запуском, третья
+  была красной и роняла общую сводку вместе с собой. Ни одна из трёх не входила в выкатку,
+  поэтому молчание было полным. Проверку, которая переписывает файлы, запускают на чистом
+  дереве: иначе её правки уедут чужим коммитом.
+- **Сделанность читается по дереву, а не по тексту, который о ней написан.** Это верно в обе
+  стороны: строка про README обеих либ была вычеркнута как сделанная, а README остался с
+  прежним числом импортёров; задача, названная владельцу несделанной, оказалась наполовину
+  закрытой и покрытой сценариями хука. Пункт плана и тело задачи описывают день, когда их
+  написали, и с тех пор не менялись.
+- **Комментарий в файле — такое же утверждение, как строка в документе.** Обоснование «строки
+  идут во всю ширину панели, иначе подсветка обрывается» было выдумано, прожило три сессии и
+  каждый раз читалось как основание вёрстку не трогать.
+- **Чужие проекты не упоминаются нигде** — ни имени репозитория, ни «портировано из», ни
+  ссылок на его файлы. Описывается то, что код делает здесь, в терминах этого проекта.

package/assets/pitfalls/git-workflow.azure.md

@@ -0,0 +1,50 @@
+# Поставка — холодная часть
+
+Ловушки: грабли, на которые уже наступали в дереве на Azure DevOps. Грузится не вместе с
+правилом, а по требованию — при обычном решении она не нужна.
+
+Правило — `git-workflow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится вторым рабочим элементом, здесь нет: делится то, что придётся откатывать порознь.
+  Сплошная правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать
+  два рабочих элемента, закрывать два PR и переносить коммиты по одному с двумя конфликтами.
+  Одна из трёх не дала коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей
+  под ветку тоже.
+- **Рабочий элемент заводится командой, а не вызовами подряд.** Доска показывает элементы своей
+  области и итерации, и заведённый мимо них в очереди работ не виден: со стороны это выглядит
+  так же, как незаведённый. Команда заведения ставит все поля разом — род, состояние,
+  исполнителя, область и итерацию, — и печатает готовую строку заведения ветки. Замеченный по
+  ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
+- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** Прогон
+  заводится и кончается на разборе файла, не начав ни одного задания: в списке он стоит
+  отказом, а внутри нет ни задания, ни лога — читается только длительность. Поэтому список
+  прогонов ветки смотрится тем же движением, что и пуш: `az pipelines runs list` по своей
+  ветке.
+- **`online` у агента на своей машине означает запущенный процесс, а не работающий конвейер.**
+  Две стороны сходятся отдельно: требования заданий и возможности самого агента в его пуле.
+  Пока пересечения нет, агент стоит `online` и не берёт ничего, а задания ждут размещённого
+  пула — по состоянию это выглядит настроенным. Владельцу называют выполненное задание с его
+  номером, а не строку состояния.
+- **Вход в реестр образов из агента, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

package/assets/pitfalls/git-workflow.github.md

@@ -0,0 +1,78 @@
+# Поставка — холодная часть
+
+Ловушки: грабли, на которые уже наступали в дереве на GitHub. Грузится не вместе с
+правилом, а по требованию — при обычном решении она не нужна.
+
+Правило — `git-workflow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
+  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
+  закрывать два PR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
+  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
+- **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
+  привязана, и задача попадает на неё только явным добавлением: две задачи так и простояли вне
+  очереди работ, потому что шаг переписывали руками. Команда заведения делает все четыре — issue,
+  номер в его заголовке, добавление на борду, начальную колонку, — и печатает готовую строку
+  заведения ветки. Замеченный по ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца. Разница между читающим и
+  пишущим вызовом в самом тексте команды не видна: личность приходит окружением, поэтому у
+  вызова на запись токен называется явно, а открытая заявка проверяется ответом хостинга о её
+  авторе — напечатанная ссылка говорит, что заявка создана, и молчит о том, кем. Чинится это
+  только переоткрытием: автора у заявки не сменить.
+- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** GitHub
+  заводит такой прогон и на ветке, на которую ни один триггер не подписан: в списке он стоит
+  отказом, а внутри у него нет ни задания, ни лога — читается только длительность. Поэтому
+  список прогонов ветки смотрится тем же движением, что и пуш — `gh run list --branch <ветка>`.
+  Один такой отказ простоял в списке до мержа, и на него никто не посмотрел: выкатка после
+  мержа отказала ровно тем же.
+- **Прогон, не вставший на пуш, возвращается повтором события, а не разбором ветки.** Замером
+  проверены обе законные дороги: и открытие PR, и пуш в уже открытый PR прогон заводят —
+  текстовый коммит и учётная запись, которой пушат, тут ни при чём. Пропавшие события пришлись
+  на час, когда хостинг отвечал `429` на загрузке действия и `503` на API, а списком прогонов
+  «не завёлся» от «не создан» не отличить. Поэтому вершину без прогона называет сверка очереди
+  работ, а событие возвращается новым коммитом либо перезакрытием PR.
+- **Красное на шаге подготовки задания — отказ хостинга, а не дефект ветки.** Раннер не смог
+  скачать действие чекаута и получил `429 Too Many Requests`; до кода прогон при этом не дошёл
+  вовсе. Лечится перезапуском прогона, и от красного по существу отличается тем, на каком шаге
+  оно встало: три прогона одного дня упали именно так.
+- **Контекст `runner` в `env` задания отбивает весь файл конвейера.** Там доступны только
+  `github`, `needs`, `strategy`, `matrix`, `vars`, `secrets` и `inputs`; `runner` появляется на
+  уровне шага, где то же значение приходит переменной окружения. Такой файл не принимается
+  вовсе: прогон кончается за ноль секунд, не начав ни одного задания. Разбор YAML этого не
+  ловит — синтаксис верный, а доступность контекстов синтаксисом не является.
+- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
+  конвейер.** Две стороны сходятся отдельно: `runs-on` у заданий и метки самого раннера. Пока
+  пересечения нет, раннер стоит `online` и не берёт ничего, а задания уходят в облако — по
+  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
+  не строку состояния.
+- **Раннер на своей машине делает прогон общим ресурсом, и стенд у прогонов один.** Порт,
+  имя базы и каталог сборки зашиты в дереве одним значением на всех: два прогона разом
+  поднимают два стенда на один порт, и второй падает целиком. Дороже всего не падение, а его
+  вид — в отчёте оно выглядит десятком красных спек про экраны, то есть дефектом правки,
+  которого нет; три прогона подряд так и упали на трёх ветках, не тронувших кода. Лечится с
+  двух сторон сразу: конвейеру объявляется группа очереди на всё дерево, а имена стенда
+  читаются из окружения с нынешними значениями в умолчании — иначе прогон и гейт пуша, зовущий
+  ту же команду, столкнутся и при очереди. Одной очереди мало, одних имён — тоже: прогоны делят
+  ещё диск, кэш сборщика и демон образов.
+- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

package/assets/pitfalls/git-workflow.gitlab.md

@@ -0,0 +1,49 @@
+# Поставка — холодная часть
+
+Ловушки: грабли, на которые уже наступали в дереве на GitLab. Грузится не вместе с
+правилом, а по требованию — при обычном решении она не нужна.
+
+Правило — `git-workflow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
+  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
+  закрывать два MR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
+  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
+- **Задача заводится командой, а не вызовами подряд.** Доска показывает те issue, чью метку
+  знает, и задача без метки списка в очереди работ не видна: со стороны это выглядит так же, как
+  незаведённая. Команда заведения ставит всё разом — issue, номер в его заголовке, метку списка,
+  исполнителя, — и печатает готовую строку заведения ветки. Замеченный по ходу дефект проходит
+  тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор MR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: MR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
+- **Невалидный файл конвейера виден отказом сразу после пуша, а не упавшим заданием.** Конвейер
+  на такой файл не заводится вовсе: в списке стоит запись об ошибке разбора, а внутри нет ни
+  задания, ни лога. Поэтому список конвейеров ветки смотрится тем же движением, что и пуш —
+  `glab ci list --branch <ветка>`, — а сам файл до пуша судит проверка `.gitlab-ci.yml` в
+  проекте.
+- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
+  конвейер.** Две стороны сходятся отдельно: `tags` у заданий и теги самого раннера. Пока
+  пересечения нет, раннер стоит `online` и не берёт ничего, а задания ждут общего раннера — по
+  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
+  не строку состояния.
+- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

package/assets/pitfalls/spec-driven.md

@@ -0,0 +1,36 @@
+# Документация проекта — холодная часть
+
+Ловушки: грабли, на которые уже наступали. Грузится не вместе с правилом, а по
+требованию — при обычном решении она не нужна.
+
+Правило — `spec-driven`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **`tasks.md` в спеке не заводить.** Шаги — артефакт сессии, им место в ветке или в описании
+  PR. Как только в директории появляются «шаги», спек снова становится планом и умирает после
+  мержа.
+- **Спек описывает установившееся, а не предстоящее.** Единственное место, где он говорит о
+  будущем, — `proposed/<фича>/`. После выкатки его текст вливается в спек домена, директория
+  удаляется, идентификаторы сценариев не меняются.
+- **Семантику полей не сверяет ничто.** Проверка знает имена процедур, коды отказа и связь
+  сценариев с тестами; что означает пустое поле — не знает. Правка `.proto` поэтому тянет
+  спеки всех доменов, чьи процедуры она задела, в той же ветке.
+- **Живость символа считается совпадением имени по всему дереву, а не вызовом.** Символу
+  хватает второго упоминания где угодно — в чужом поле с тем же именем, в атрибуте разметки.
+  Место, где правило исполняется на самом деле, подтверждается только чтением кода.
+- **Якорь в `tools/*.mjs` сверяется почти ничем:** живость считается только для `.ts`, а
+  исходники обходятся по `apps`, `libs` и `prisma`. Правило, привязанное к проверке, поэтому
+  читается вместе с её телом.
+- **Зелёная проверка не значит, что структура верна.** Спутники с привязкой сначала лежали
+  рядом с законами, и проверка была зелёной именно потому, что структура совпадала с тем,
+  чего проверка сама и ждала.
+- **Конфликт мержа в спеке разрешается сохранением обеих сторон, а не выбором одной.** Две
+  ветки дописывают в конец одних и тех же списков — сценариев, правил, строк привязки, — и
+  обе стороны верны: конфликт здесь не спор, а две дописи в одно место. Номера сценариев при
+  разрешении не пересчитываются: идентификатор — ключ связи с тестами, и сдвиг номеров рвёт
+  сверку у соседей, которых правка не касалась. Порядок сохранённых сторон держится
+  одинаковым в `spec.md`, `scenarios.md` и `implementation.md`: иначе правило, его сценарий и
+  его привязка перестают находиться друг по другу. После разрешения гоняется
+  `npm run check:specs` — конфликт в спеке кода не задевает, и ни сборка, ни линтеры его не
+  увидят.

package/assets/pitfalls/styling-bem.md

@@ -0,0 +1,45 @@
+# Оформление — холодная часть
+
+Ловушки: грабли, на которые уже наступали. Грузится не вместе с правилом, а по
+требованию — при обычном решении она не нужна.
+
+Правило — `styling-bem`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **`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/pitfalls/task-flow.md

@@ -0,0 +1,62 @@
+# Ведение работы — холодная часть
+
+Ловушки и поведение по разборам происшествий. Грузится не вместе с правилом, а по требованию:
+при обычном решении она не нужна — она нужна тому, кто разбирает промах или спорит с гардом.
+
+Правило — `task-flow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Папка называется именем ветки, один в один.** Хук запуска ищет её по
+  `git branch --show-current`, и папка, названная иначе, не находится ничем: работа идёт с
+  пустым контекстом, а владельца просят пересказать то, что уже записано.
+- **Разбор просьбы задним числом не переписывается.** Пересказ незаметно подгоняется под уже
+  сделанное, и сверять результат становится не с чем. Решение, изменённое по ходу, дописывается
+  в ход работы, а не правится в разборе.
+- **Договорённость о продукте не кладётся в папку задачи.** Папка умирает с мержем, а
+  договорённость обязана его пережить: её сценарии получают номера в общей нумерации домена,
+  и на них ссылаются заголовки тестов. Обратное тоже верно — ход работы не кладётся в
+  `proposed/`: спек, в котором завелись шаги, снова становится планом и умирает после мержа.
+- **У меню нет строки «вопрос не тот».** Меню годится для выбора значения из закрытого набора;
+  пока постановка вопроса не подтверждена, отвергнуть её владельцу нечем — он выбирает из
+  вариантов, выведенных из неверной посылки. Настройки владельца, требующие меню, требование
+  не снимают: тогда к каждому вопросу добавляется свободный вариант, и он же — единственное
+  место, где вопрос отвергается целиком. Три вопроса ушли одним меню, у одного постановка была
+  ложной, и сказать «вопрос не тот» было нечем. Выбор слова, имени и термина узким вопросом не
+  является никогда.
+- **Субагент вопросов владельцу не задаёт.** Ни роли, ни конвейер до него не достучатся —
+  они возвращают текст главному агенту. Поэтому разбор ведёт главный агент, а роли стоят по
+  обе стороны от него.
+- **Если дефект чинится правкой одного общего числа, спроси владельца, тем ли способом ты его
+  чинишь.** Замер показывает, что дефект ушёл, — но не то, что причину вылечили. В одной
+  задаче так ушли две правки подряд: сначала подняли общее число у соседнего узла, потом
+  перенесли узел в другое место разметки. Обе владелец отверг, а нужный способ назвал сам.
+  Спрашивают до правки, а не показывают замер после.
+- **Путь, предложенный человеку, судится числом его шагов и тем, чем ему для этого надо
+  владеть.** Со стороны кода вариант выглядит дешёвым — «меньше путей», «строку запуска не
+  трогаем», — а человеку он стоит захода на сервер. Однажды рекомендуемым вариантом так стояла
+  выдача токена, за которой владельцу надо было идти по ssh в работающий контейнер; отбивал
+  этот вариант он сам. Цена называется со стороны того, кто пойдёт: сколько шагов и что ему для
+  них нужно. Пересказ действующего порядка без такой оценки владелец читает как одобрение.
+- **Эпик по теме читается до того, как решается раскладка.** Замысел эпика держит решения,
+  которые пережили десяток задач, и разведка по коду их не находит: снятое решение следа в
+  дереве не оставляет. Домен, заведённый генератором и снесённый через полчаса, стоял в замысле
+  прямым запретом — но замысел открыли уже после того, как он был заведён во второй раз.
+- **Работа, которая разбирает чужую папку задачи, разбирает и свою — одним коммитом.** Свою
+  папку она заводит наравне со всеми: исключения из этого требования нет. Круг, которым
+  исключение оправдывали, закрывается не отказом от папки, а порядком разбора: последний
+  коммит снимает обе, и после работы неубранного не остаётся. Однажды такой разбор оставил
+  свою папку, и на неё пришлось заводить третью задачу — лечится это порядком, а не правом
+  работать без замысла на диске. Как разобрать две папки — паттерн `task-flow-archive`.
+- **Слово для нового понятия берётся из `docs/GLOSSARY.md` или заводится там же.** Третий файл
+  папки задачи называется `progress.md`, а не `journal.md`, ровно поэтому: журнал в этом
+  дереве один, и он другой.
+- **Черновик папки задачи называется тем же коротким именем, что и будущая ветка.** Команда
+  заведения ищет черновик по нему и, не найдя, молча собирает папку с образца: работа при этом
+  идёт дальше, а разбор просьбы остаётся лежать в брошенном каталоге, и следующий заход
+  расспрашивает владельца заново. Имя черновику дают словами просьбы, а ветке — терминологией
+  договорённости; те же слова, да не те же.
+
+## Поведение исполнителя — по разборам происшествий
+
+Переезжает из правила следующей задачей эпика.

package/assets/pitfalls/testing.md

@@ -0,0 +1,70 @@
+# Проверка — холодная часть
+
+Ловушки: грабли, на которые уже наступали. Грузится не вместе с правилом, а по
+требованию — при обычном решении она не нужна.
+
+Правило — `testing`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Зелёный `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 % в задании конвейера и проходили на той же машине вне его.
+- **Стенд, поднятый предыдущим шагом, останавливается перед съёмкой.** Оставленный работать, он
+  соревнуется за машину с тем, что снимают, и делает исход прогона зависящим от того, чем занят
+  сосед. Нагрузка, которую задание создаёт себе само — соседняя витрина, только что законченная
+  сборка, — ничем не отличается от чужой.
+- **Свой стенд снимается перед тем, как звать набор.** Прогон переиспользует поднятое на его
+  портах, и стенд, оставленный для замера, отдаёт ему чужую сборку с чужими данными. Красное при
+  этом приходит не строкой про занятый порт, а десятком спек про экраны — то есть выглядит
+  дефектом правки: за один заход так покраснели сначала шесть новых тестов, потом гейт пуша, и
+  оба раза причиной был свой же стенд. Разобранный занятый порт эту сторону не закрывает: он про
+  чужой стенд, а этот — про свой.
+- **Разбор упавшего кадра начинается с чисел, а не с картинки расхождения.** Доля площади
+  говорит, сколько разошлось, и молчит о том, что именно: сдвиг всего кадра на пиксель,
+  переставленные строки и рябь на сглаженных уголках выглядят на картинке одинаково — «стало
+  другим». Читаются координаты разошедшихся точек и величина расхождения по каналу: сдвинутые
+  границы блоков — это раскладка, разошедшийся текст при неподвижных границах — это данные,
+  единица-две по каналу на кривых краях — это цвет. Три расхождения одного набора разобрались
+  ровно так, и ни одно из трёх не оказалось дефектом экрана.
+- **Ожидаемое значение теста не берётся из кода, который тест проверяет.** Вывезенное из
+  проверяемой либы, оно делает тест зелёным при любом значении: «колесо показывает пять строк»
+  сходится и тогда, когда строк стало три. Ожидаемое пишется числом в самой спеке рядом с
+  проверкой, а общий модуль сквозных спек держит приёмы — открыть, дождаться, снять со
+  страницы, — но не то, что от страницы ожидается.