@rt-tools/agent-kit 0.8.0 → 0.8.1

package/assets/checks/check-reuse.mjs

@@ -14,7 +14,7 @@
  *
  * Отличий от гарда два. Первое: инвентарь кита не читается — гард спрашивает диск, потому что
  * отвечает одной правке, а сплошной проверке важно накопленное, и пропавший пакет молча
- * обнулял бы сводку. Второе: маркер `native-ok` снимает свою строку, а не весь файл.
+ * обнулял бы сводку. Второе: маркер `native-ok` снимает свою строку и следующую, а не весь файл.
  *
  * Накопленное к моменту заведения проверки лежит в tools/reuse-allowlist.json и отказом не
  * считается: гейт падает на новом расхождении, а старое остаётся видимым числом в сводке.
@@ -85,14 +85,16 @@ function judged(path) {
 }
 
 /**
- * Строка с маркером — осознанное отступление, названное автором. Снимается только она сама:
- * весь файл маркер не гасит, иначе один разрешённый случай прикрывал бы соседние.
+ * Маркер — осознанное отступление, названное автором. Снимается строка, где он стоит, и та, что
+ * идёт следом: в разметке маркер ставится комментарием над кодом, потому что форматировщик
+ * разносит длинный тег по строкам и уводит первый атрибут со строки имени тега — признак считает
+ * имя тега, а маркер оказывается ниже. Дальше следующей строки маркер не достаёт: весь файл он
+ * не гасит, иначе один разрешённый случай прикрывал бы соседние.
  */
 function withoutMarked(text) {
-    return text
-        .split('\n')
-        .filter((line) => !line.includes('native-ok'))
-        .join('\n');
+    const lines = text.split('\n');
+
+    return lines.filter((line, index) => !line.includes('native-ok') && !lines[index - 1]?.includes('native-ok')).join('\n');
 }
 
 const allowlist = JSON.parse(readFileSync(join(ROOT, ALLOWLIST), 'utf8'));

package/assets/patterns/reuse-first-extend.md

@@ -82,9 +82,18 @@ grep -rn "<похожий приём>" libs/admin libs/site --include='*.html' |
 <input type="tel" qa-dataid="phone-input" />
 ```
 
-Маркер `native-ok` ставится в той же строке и объясняет, **чего именно нет в ките**. «Эти
-строки были здесь раньше» причиной не считается: гард вычёркивает из проверяемого текста то,
-что уже лежит в файле, поэтому отказ означает новый текст.
+Маркер `native-ok` объясняет, **чего именно нет в ките**. «Эти строки были здесь раньше»
+причиной не считается: гард вычёркивает из проверяемого текста то, что уже лежит в файле,
+поэтому отказ означает новый текст.
+
+Стоит он комментарием строкой выше кода или в самой строке — снимаются обе. В разметке годится
+только первое: форматировщик разносит тег, у которого атрибуты не влезли в предел ширины, по
+строкам, и первый атрибут всегда уезжает на строку ниже имени тега. Признак считает имя тега,
+то есть первую строку, а маркер, поставленный атрибутом, оказывается на второй и не снимает
+ничего. Короткий тег форматировщик не трогает — и маркер работает ровно до тех пор, пока к тегу
+не добавили ещё один атрибут.
+
+Дальше следующей строки маркер не достаёт: он снимает свой случай, а не блок вокруг себя.
 
 Сверка идёт без отступов — при переезде блок меняет отступ, оставаясь тем же кодом.
 

package/assets/rules/reuse-first.md

@@ -17,7 +17,7 @@ description: Правило под «Закон о единообразии пр
 | готовое                          | компоненты кита `@rt-tools/ui-kit-v2` с префиксом `rt-` — сегодня их больше семидесяти — и базовые классы без селектора, наследуемые в `@Component` экрана |
 | раскладка страниц, форм и окон   | `apps/<app>/src/styles/`, применяется директивами BEM                                                                                                      |
 | оформление части приложения      | файл `.scss` рядом с компонентом                                                                                                                           |
-| отступление, решённое владельцем | маркер `native-ok` в той же строке с объяснением                                                                                                           |
+| отступление, решённое владельцем | маркер `native-ok` с объяснением — комментарием строкой выше или в самой строке                                                                            |
 
 ## Где это лежит
 

package/assets/skills/agent-kit-extend.md

@@ -0,0 +1,149 @@
+---
+name: agent-kit-extend
+description: Готовые примеры того, как дерево дописывает своё поверх пакета правил — надстройка над разложенным текстом, своя ветка карты гейта, своя функция профиля, свой признак единообразия, свой закон и правило. Брать, когда пакетный текст говорит не то, что верно здесь, гейт требует не то правило, гард судит не по тем путям, или своё поведение надо дописать, не трогая пакет. Где что настраивается и как устроена раскладка — скил agent-kit; форма нового скила — write-a-skill.
+---
+
+# Как дописать своё поверх пакета
+
+Скил `agent-kit` называет, **где** настраивается каждый род правки. Здесь — **как** выглядит
+сама правка, на готовых примерах, и чем каждая проверяется.
+
+Одно правило общее для всех пяти: разложенный файл не правится на месте. Он несёт шапку
+`rt-kit v… · <ресурс> · <сумма>`, правка в нём теряется на следующей раскладке и до тех пор
+выглядит применённой, а `sync` на такой файл отказывает вместо того, чтобы переписать молча.
+
+## Когда брать
+
+- Пакетный текст говорит не то, что верно здесь: имена, пути, приёмы этого дерева.
+- Гейт требует под файл не то правило — или молчит там, где правило есть.
+- Гард судит не по тем путям: чужие корни, свой набор проверок, своя форма ветки.
+- Заводится своё — признак единообразия, проверка, закон с правилом, — чего пакет не везёт.
+
+## Текст: надстройка сливается по разделам
+
+Файл кладётся в `overrides/<идентификатор ресурса>` — путь повторяет ресурс один в один:
+`rules/testing.md` надстраивается файлом `rules/testing.md`.
+
+```markdown
+## Ловушки этого дерева
+
+- **Снимок дерева правится тем же коммитом, что и объявление.** Иначе установка у соседа
+  ставит не то, что стоит здесь.
+```
+
+| Заголовок в надстройке | Что происходит            |
+| ---------------------- | ------------------------- |
+| есть у пакета          | раздел замещается целиком |
+| нет у пакета           | дописывается в конец      |
+| есть, но тело пустое   | раздел пакета снимается   |
+
+**Замещение — целиком, и это главная ловушка.** Свой пункт, дописанный под пакетным заголовком
+`## Ловушки`, уносит все пакетные пункты этого раздела разом, и пропажу не видно ничем: файл
+выглядит собранным. Поэтому заголовок в примере выше свой. Пакетный заголовок берут только
+тогда, когда пакетный текст здесь неверен и его правда надо снять.
+
+Проверяется раскладкой: `sync`, затем `sync --check` — и глазами по разложенному файлу, на
+месте ли пакетные разделы.
+
+От ресурса целиком отказываются не здесь, а списком `skip` в конфиге: надстройка правит текст,
+`skip` отменяет файл.
+
+## Гейт: своя ветка решает раньше умолчания
+
+Гейт спрашивает `skill_for` — она печатает имя правила или молчит. Молчание значит «правила на
+это нет», и правка проходит.
+
+```bash
+skill_for() {
+    kind="$1"; target="$2"; written="$3"
+
+    case "$kind" in
+        edit)
+            case "$target" in
+                # Частное — всегда раньше общего: файл истории не файл компонента.
+                *.stories.ts) printf '%s\n' 'showcase'; return 0 ;;
+            esac
+            ;;
+    esac
+
+    # Всё остальное разбирает умолчание пакета — иначе оно теряется целиком.
+    command -v skill_for_default >/dev/null 2>&1 && skill_for_default "$kind" "$target" "$written"
+
+    return 0
+}
+```
+
+Две вещи здесь обязательны. **Порядок веток:** первое совпадение выигрывает, и общая ветка,
+поставленная выше частной, съедает её молча. **Вызов умолчания:** объявив функцию заново и не
+позвав `_default`, дерево остаётся без всех пакетных веток сразу — а выглядит это как «гейт
+перестал требовать правила».
+
+Проверяется сценариями гейта из набора пакета: они гоняют карту, ничего не раскладывая.
+
+## Гард: профиль отвечает за имена и команды
+
+Тем же приёмом объявляются функции профиля — что гонять перед пушем, какой документ едет парой,
+чем линтуется файл, что здесь считается кодом приложения, какая форма ветки законна.
+
+```bash
+# Какой документ обязан ехать тем же коммитом. Печатает образец пути или молчит.
+rt_docs_pair_for() {
+    case "$1" in
+        *.spec.ts) return 0 ;;
+        libs/kit/src/*/*.component.ts) printf '%s' "${1%/*}/CONTEXT\.md" ;;
+    esac
+}
+```
+
+Печатается **образец**, а не путь: гард сверяет им состав коммита. Умолчание зовётся так же —
+`rt_docs_pair_for_default "$@"` — везде, где своё правило случай не закрыло.
+
+Путь приходит от корня дерева. Признак по подстроке вида `*/projects/*` совпадает и с чужим
+каталогом за пределами репозитория — так запись в домашний каталог была отбита требованием
+замысла, к ней не относящимся.
+
+## Признаки и проверки: данные, а не код
+
+Признак единообразия — данные. Дерево называет наборы пакета, чьё готовое оно берёт, и
+дописывает свои файлом; совпавший ключ замещает пакетный.
+
+```json
+{
+    "sourceRoots": ["apps", "libs"],
+    "reuse": { "bundles": ["kit"], "signals": "tools/signals/own.json" }
+}
+```
+
+Объект сливается ключ за ключом: назвав один ключ раздела, дерево не теряет соседних. **Список
+— наоборот, замещается целиком**, и это ловушка: назвав `sourceRoots`, дерево получает ровно
+названное, а не пакетные корни плюс свои. «Дописать в список» и «убрать из списка» в этой записи
+неразличимы, поэтому список всегда пишется полностью.
+
+Набор объявляется по тому, что дерево **потребляет**. Дерево, в котором кит написан, а не
+позван, объявив его набор, получит советы звать кит на файлах самого кита: признак верен, но
+обращён не туда.
+
+## Свой закон и правило
+
+Пакет везёт слой правил, но не запрещает свой. Закон дерева ложится рядом с пакетными, правило
+под него — среди скилов, и связь идёт через шапку: у правила `law:` с именем закона, у паттерна
+`rule:` с именем правила. Имя, которому ничего не отвечает, отбивает сверку связности.
+
+Утверждение правила получает строку в спутнике `implementation.md` — привязку к файлу и символу.
+Утверждение, которому места в коде не нашлось, в проверяемый раздел не ставится: ему место в
+«Ловушках» прозой.
+
+Проверяется сверкой спеков — до пуша.
+
+## Частые промахи
+
+- **Правка на месте вместо надстройки.** Разложенный файл узнаётся по шапке, а не по каталогу:
+  раскладка ложится в те же `tools/` и `.claude/`, где лежит своё.
+- **Свой пункт дописан к пакетному заголовку** — пакетные пункты этого раздела ушли молча.
+- **Функция объявлена заново без вызова `_default`** — вместе со своим случаем потеряны все
+  пакетные.
+- **Общая ветка карты стоит выше частной** — частная не выполняется никогда.
+- **Замена по шаблону в файле оболочки** — `case` теряет свою `esac`, и гард с ошибкой синтаксиса
+  отвечает ненулевым кодом, то есть «правка отбита». После правки — `bash -n`.
+- **Правка ресурса пакета без сборки.** Строка запуска читает собранное, а не исходники:
+  порядок всегда один — правка, сборка, `sync`.

package/assets/skills/agent-kit.md

@@ -33,6 +33,9 @@ description: Переносимый слой правил агента — за
 `_default`. Слияние текста идёт по разделам `## `: совпавший заголовок замещает, новый
 дописывается, пустой снимает раздел пакета.
 
+Готовый пример на каждую строку этой таблицы — скил `agent-kit-extend`: как выглядит сама
+правка, чем она проверяется и чем кончается, если положить её не туда.
+
 ## Порядок
 
 Правка ресурса доезжает до дерева только через сборку пакета: строка запуска читает собранное,
@@ -108,10 +111,11 @@ npx agent-kit propose       # отправить предложения, адр
   написанная по путям, требует под него доменное правило — а оно уводит править файл на месте.
   Правка на месте теряется на следующей раскладке, и до тех пор выглядит применённой. Ветка по
   шапке ставится в карте первой и решает раньше путей.
-- **Настройки проверок сливаются на один уровень.** Верхние ключи `checks.json` ложатся поверх
-  умолчаний по одному, а вложенный объект замещается целиком: назвав один ключ борды, дерево
-  теряет остальные — и увидит это отказом «нет токена бота», то есть как неполадку машины.
-  Вложенный раздел заполняется целиком либо не заводится вовсе.
+- **Настройки проверок сливаются по ключам, а списки — замещаются.** Объект `checks.json`
+  ложится поверх умолчания ключ за ключом на любой глубине: назвав один ключ борды, дерево не
+  теряет соседних. Список приходит целиком — назвав корни исходников, дерево получает ровно
+  названное, а не умолчание вместе со своим: «дописать в список» и «убрать из списка» в этой
+  записи неразличимы.
 - **Утверждение правила переезжает вместе с кодом.** Вынесенное в надстройку перестаёт
   находиться по прежнему символу, и привязка в спутнике правила врёт молча — сверка спеков
   ловит это, но только если её позвать.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rt-tools/agent-kit",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Переносимый слой правил для агента: законы, хуки, проверки и агенты, раскладываемые в репозиторий одной командой",
   "author": "RT Team",
   "license": "Apache-2.0",