@rt-tools/agent-kit 0.11.0 → 0.13.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 не ставятся.** Селекторы объединяются вложенностью.
-- **При переносе стилей новых объявлений не появляется** — только перемещение существующих.