@rt-tools/agent-kit 0.8.2 → 0.8.3

package/README.md

@@ -63,6 +63,7 @@ npx agent-kit sync --check
 | `agents`, `commands`, `workflows` | `.claude/` | роли, слеш-команды и многошаговые прогоны |
 | `checks` | `tools/` | проверки, которые зовёт гейт |
 | `templates` | `.claude/rt-kit/templates/` | формы правила, паттерна, компаньона и надстроек |
+| `samples` | `docs/` | образцы, которые копируют в рабочий файл: папка задачи, спек домена |
 
 Правило, паттерн и скил ложатся одинаково — все три скилы; различает их `kind` во вступлении
 файла. Скил без закона стоит рядом с лестницей, а не в ней: он не про то, что должно быть верно

package/assets/agents/rules-reviewer.md

@@ -0,0 +1,83 @@
+---
+name: rules-reviewer
+description: Читает семью текстов слоя правил целиком — закон, все правила под ним и все паттерны при них — и ищет то, чего не считает машина: два текста, говорящих об одном разное, и случай, которого не назвал ни один. Файлов не правит. Использовать перед выпуском новой редакции пакета правил и после правки закона или правила.
+tools: Read, Grep, Glob, Bash
+---
+
+Ты читаешь семью текстов слоя правил и ищешь расхождения смысла. Отвечаешь **по-русски**.
+
+Твой результат — список находок. Не правки: ты ничего не меняешь.
+
+Промах в этих текстах уезжает ко всем деревьям разом и находит его тот, кто пошёл за правилом и
+сделал не то. Считаемое — недостающий раздел, правило без паттерна, имя соседа, которому ничего
+не отвечает — уже ловит проверка. Тебе остаётся то, что видно только чтением.
+
+## Чего делать нельзя
+
+- **Никаких git-команд вообще**, включая `status` и `diff`. Историю ведёт главный агент.
+- Ничего не править: ни закон, ни правило, ни паттерн. Ты возвращаешь находки.
+- Не пересказывать найденное своими словами: находка без дословной цитаты не проверяется ничем,
+  и человек не отличит настоящее расхождение от твоего прочтения.
+- Не считать того, что уже считает проверка полноты текстов. Повтор её вывода вытесняет из
+  ответа то, ради чего тебя и звали.
+- Не судить о дереве, в котором ты запущен. Тексты пакета переносятся, и что из них разложено
+  здесь — не их предмет.
+
+## По чему идёшь
+
+Семья — это **один закон, все правила под ним и все паттерны при этих правилах**. Имя закона
+тебе даёт вызывающий. Пакет целиком не читается: текстов в нём больше десяти тысяч строк, и
+прочитанные разом они дают крошку по каждому файлу вместо находок.
+
+Правило принадлежит закону по полю `law:` в его шапке, паттерн правилу — по полю `rule:`.
+Приставка имени ненадёжна: её несут не все.
+
+**Все виды правила читаются, а не выбранный.** У одного ресурса бывает несколько редакций —
+`git-workflow.github`, `git-workflow.gitlab`, `git-workflow.azure`. Дерево раскладывает одну, и
+остальные не читает никто: разойдясь, они молчат до первого дерева, выбравшего другую.
+
+**Суффикс требования видом не является.** `entity-conventions.needs-admin`,
+`observability.needs-app` — правила, которые дерево берёт, только объявив нужную черту. В поле
+`rule:` у паттерна стоит голое имя, без обоих суффиксов: собранная по имени с суффиксом семья
+приходит без паттернов, и пустота эта выглядит как их отсутствие. Пришедшая к тебе семья без
+единого паттерна — повод сказать об этом, а не молча разобрать что дали.
+
+Ищешь два рода находок, и они разные.
+
+**Расхождение — два места, говорящих об одном разное.** Правило требует того, что паттерн при
+соседнем правиле запрещает. Закон называет одно число, правило — другое. Паттерн показывает
+приём, который правило объявило отвергнутым. Сюда же — одно понятие под двумя именами и одно имя
+над двумя понятиями.
+
+**Пробел — случай, которого не назвал ни один текст семьи.** Статья закона, под которую ни в
+одном правиле нет ни строки. Развилка, у которой описана одна ветка из двух. Отказ, о котором
+сказано, что он бывает, и не сказано, что делать. Раздел «Чего из закона здесь нет», который
+молчит о том, чего в дереве действительно нет.
+
+**Граф хода — такое же место расхождения, как проза.** Он стоит в правиле разделом «Ход»
+блоком `mermaid` и изображает тот же ход, что описан ниже словами: ветка графа, которой в прозе нет, и статья, до
+которой по графу не дойти, — расхождение того же рода, что и два текста об одном. Правится он тем
+же изменением, что и проза, и разойдясь, обе стороны читаются как действующие.
+
+Три места, где расхождения заводятся чаще прочего, — проверь каждое:
+
+- **«Чего из закона здесь нет»** — его не читает ни одна сверка, и неправда живёт в нём сколько
+  угодно: раздел говорит об отсутствии механизма, а механизм давно заведён, и заметить это может
+  только тот, кто пошёл его искать.
+- **Числа** — счёт правил, статей, шагов, строк. Они стареют без единой правки рядом.
+- **Ловушки** — их пишут по случаю и не перечитывают: приём, который они запрещают, мог с тех
+  пор стать рабочим.
+
+## Что возвращаешь
+
+Список находок, самая дорогая первой. Роды не смешивай — сперва расхождения, потом пробелы.
+
+У **расхождения**: имена обоих ресурсов, обе цитаты дословно, и одной фразой — чем именно они
+расходятся и что исполнитель сделает не так, пойдя за той или другой.
+
+У **пробела**: имя ресурса, в котором его недостаёт, цитата места, где он должен был стоять
+(или имя раздела, если места нет вовсе), и что случится, когда этот случай наступит. Второй
+цитаты у пробела не бывает — не выдумывай её.
+
+Находок нет — так и скажи. Пустой ответ дешевле выдуманного: по выдуманному правят настоящие
+тексты.

package/assets/checks/check-dupes.mjs

@@ -36,8 +36,9 @@
  *
  * Ненулевой код возврата и перечень расхождений.
  */
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 
 import { allowlistOf, CONFIG, ROOT } from './rt-kit-checks.config.mjs';
 
@@ -76,6 +77,56 @@ function collectFiles(dir) {
     return files;
 }
 
+/**
+ * Каталог объявлений внешнего пакета — разрешением модуля, а не путём в `node_modules`.
+ *
+ * Точек разрешения несколько: корень дерева и каждый его подпроект, объявивший этот пакет
+ * зависимостью. Пакет подпроекта в корне не лежит вовсе, и разрешение от корня его не находит;
+ * менеджер при этом вправе держать рядом несколько версий сразу, и обход хранилища по образцу
+ * пути выбрал бы ту, которую никто не ставит.
+ *
+ * Не нашлось — `null`, и внешние наборы просто не считаются: дерево без этого пакета должно
+ * получать сверку своих повторов, а не отказ чтения каталога.
+ */
+function resolveExternalDir({ package: name, dir }) {
+    for (const from of [ROOT, ...holdersOf(name)]) {
+        try {
+            const manifest = createRequire(join(from, 'package.json')).resolve(`${name}/package.json`);
+            const found = join(dirname(manifest), dir);
+            if (existsSync(found)) {
+                return found;
+            }
+        } catch {
+            // Эта точка пакета не видит — пробуется следующая.
+        }
+    }
+
+    return null;
+}
+
+/** Подпроекты, объявившие пакет зависимостью: их манифесты и есть точки разрешения. */
+function holdersOf(name) {
+    const found = [];
+    for (const root of SOURCE_ROOTS) {
+        if (!existsSync(join(ROOT, root))) {
+            continue;
+        }
+        for (const entry of readdirSync(join(ROOT, root), { withFileTypes: true })) {
+            const manifest = join(ROOT, root, entry.name, 'package.json');
+            if (!entry.isDirectory() || !existsSync(manifest)) {
+                continue;
+            }
+            const declared = JSON.parse(readFileSync(manifest, 'utf8'));
+            const fields = [declared.dependencies, declared.peerDependencies, declared.devDependencies];
+            if (fields.some((field) => field?.[name])) {
+                found.push(join(ROOT, root, entry.name));
+            }
+        }
+    }
+
+    return found;
+}
+
 /** Корень либы: путь до каталога `src`. Повтор внутри одной либы повтором не считается */
 function libOf(path) {
     const parts = path.split('/');
@@ -116,8 +167,13 @@ const MIN_TABLE_PAIRS = 2;
 /**
  * Пакеты, чьи наборы считаются наравне с либами. Своё перечисление под уже
  * объявленный там набор — такая же копия, как и между двумя либами.
+ *
+ * Имя пакета и каталог внутри него объявляет дерево; путь в `node_modules` здесь не
+ * зашивается. Пакет, объявленный зависимостью подпроекта, в корневом `node_modules` не лежит
+ * вовсе — менеджер держит его в своём хранилище, — и проверка кончалась отказом чтения
+ * каталога, не дойдя до сверки ни разу.
  */
-const EXTERNAL_ENUM_SOURCES = ['node_modules/@rt-tools/utils/esm/lib/interfaces'];
+const EXTERNAL_ENUM_SOURCES = CONFIG.externalEnums ?? [];
 
 const exportsByName = new Map();
 const settingsByName = new Map();
@@ -188,10 +244,14 @@ for (const path of SOURCE_ROOTS.flatMap((root) => collectFiles(root))) {
     collectEnums(text, lib);
 }
 
-for (const dir of EXTERNAL_ENUM_SOURCES) {
-    for (const entry of readdirSync(join(ROOT, dir), { withFileTypes: true })) {
+for (const source of EXTERNAL_ENUM_SOURCES) {
+    const dir = resolveExternalDir(source);
+    if (!dir) {
+        continue;
+    }
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
         if (entry.isFile() && entry.name.endsWith('.d.ts')) {
-            collectEnums(readFileSync(join(ROOT, dir, entry.name), 'utf8'), dir.replace('node_modules/', ''));
+            collectEnums(readFileSync(join(dir, entry.name), 'utf8'), `${source.package}/${source.dir}`);
         }
     }
 }

package/assets/checks/check-specs.mjs

@@ -93,8 +93,32 @@ const E2E_ROOTS = CONFIG.e2eRoots;
  * выглядит как правило без якоря. Заглавные и десять букв нужны ради `api.Dockerfile`:
  * без них правило про режим исполнения образа считалось правилом с пустой привязкой,
  * а привязать его больше не к чему — режим объявлен ровно там.
+ *
+ * Символ — любая буква, а не только латинская: тексты, которые исполняет модель, написаны
+ * своим языком, и латиницей в них называется ровно то, что утверждения не держит — имя поля
+ * шапки, имя инструмента. Привязанное к имени поля утверждение остаётся зелёным, когда текст
+ * переписан целиком. Алфавит не перечисляется диапазонами: перечисленные молча не покрывают
+ * соседнего, и промах выглядит отсутствием привязки. Путь при этом остаётся латинским — он
+ * адрес в дереве, а не слово текста.
+ */
+const ANCHOR = /`([\w./-]+\.[A-Za-z]{2,10}):(\p{L}[\p{L}\p{N}_-]*|_[\w-]*)`/gu;
+/**
+ * Явный вердикт вместо якоря: статья, которой в дереве исполняться негде. Так бывает
+ * законно — правило говорит о службе, которой дерево не держит, или о движении человека,
+ * до которого проверке не дотянуться: кнопку слияния нажимают в браузере, где хуков нет
+ * вовсе. Якорь такой статье можно поставить только в файл, который её не исполняет, —
+ * проверка примет, а читателю совратёт.
+ *
+ * Принимается вердикт с причиной, а не одно слово: пустой он становится способом закрыть
+ * любую строку, и таблица за месяц превращается в список отговорок. Порог длины — та же
+ * мера, что у обхода гарда документов: причина короче его причиной не считается.
+ *
+ * Конец слова ищется отрицательным просмотром, а не `\b`: границей слова JavaScript знает
+ * только латиницу, и после кириллической буквы её нет вовсе — вердикт не опознавался ни
+ * разу.
  */
-const ANCHOR = /`([\w./-]+\.[A-Za-z]{2,10}):([A-Za-z_][\w-]*)`/g;
+const VERDICT = /^\s*(?:\*\*)?Не (?:исполняется|применимо|проверяется)(?![\p{L}\p{N}_])/u;
+const VERDICT_MIN = 40;
 /** Строка шапки, объявляющая либы, чьи процедуры домен обслуживает */
 const PROCEDURE_ROOTS = /^\*\*Процедуры:\*\*\s*(.+)$/;
 const BACKTICKED = /`([^`]+)`/g;
@@ -204,9 +228,19 @@ function bulletsOf(lines) {
 
 const escapeForRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\-]/g, '\\$&');
 
-/** Символ ищется как слово: подстрока дала бы ложное совпадение на префиксе. */
+/**
+ * Символ ищется как слово: подстрока дала бы ложное совпадение на префиксе.
+ *
+ * Границы слова считаются буквой любого алфавита, а не `\b`: он в JavaScript знает буквой
+ * только латиницу, и `\bСемья\b` не совпадает ни разу — привязка на русском слове читалась
+ * как ведущая в файл, где этого слова нет, при том что слово стоит там первой же строкой.
+ */
 function fileHasSymbol(path, symbol) {
-    return new RegExp(`\\b${escapeForRegExp(symbol)}\\b`).test(read(path));
+    // Дефис здесь не экранируется: вне класса символов он ничего не значит, а под флагом `u`
+    // лишнее экранирование — уже отказ разбора. Общий экранировщик его защищает, потому что
+    // рассчитан и на класс тоже, и `task-flow` роняло всю сверку целиком.
+    const word = symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![\\p{L}\\p{N}_])${word}(?![\\p{L}\\p{N}_])`, 'u').test(read(path));
 }
 
 /**
@@ -287,7 +321,12 @@ function checkRuleImplementation(specFile, text, mapFile, heading = '## Прав
         if (!head || head === 'Правило' || head === 'Статья' || /^-+$/.test(head)) {
             continue;
         }
-        rows.set(head, { anchors: [...cells[2].matchAll(ANCHOR)], used: false });
+        const cell = cells[2].trim();
+        rows.set(head, {
+            anchors: [...cells[2].matchAll(ANCHOR)],
+            verdict: VERDICT.test(cell) && cell.length >= VERDICT_MIN,
+            used: false,
+        });
     }
 
     for (const bullet of bullets) {
@@ -301,13 +340,17 @@ function checkRuleImplementation(specFile, text, mapFile, heading = '## Прав
             report(
                 mapFile,
                 `правило без привязки: «${head.slice(0, 60)}…» — допиши строку с \`файл:символ\`, ` +
-                    'либо перенеси правило в «Открытые вопросы» как Q-N'
+                    'вердиктом «Не исполняется» с причиной либо перенеси правило в «Открытые вопросы» как Q-N'
             );
             continue;
         }
         row.used = true;
-        if (!row.anchors.length) {
-            report(mapFile, `у правила «${head.slice(0, 60)}…» пустая привязка`);
+        if (!row.anchors.length && !row.verdict) {
+            report(
+                mapFile,
+                `у правила «${head.slice(0, 60)}…» пустая привязка — поставь \`файл:символ\` ` +
+                    'либо вердикт «Не исполняется», «Не применимо», «Не проверяется» с причиной'
+            );
         }
         for (const [, path, symbol] of row.anchors) {
             if (!exists(path)) {
@@ -883,9 +926,11 @@ for (const domain of domains) {
 
     const found = walk(base, (name) => name === 'scenarios.md').flatMap(parseScenarios);
 
-    // Префикс судится в пределах одного спека, а не всего дерева домена: у поддомена он свой, и
-    // по номеру видно, о чём сценарий. Два префикса в одном спеке по-прежнему означают, что
-    // предмет описан дважды.
+    // Префикс принадлежит домену вместе с его поддоменами, а не отдельному каталогу. Домен
+    // делится тогда, когда его спек перерос предел длины, и сценарии переезжают в поддомены
+    // прежними: номер — единственное, чем сценарий связан с заголовком теста, и своя нумерация
+    // у каждого поддомена означала бы пересчёт всех номеров разом. Два префикса в одном спеке
+    // по-прежнему означают, что предмет описан дважды.
     const prefixesOf = new Map();
     for (const scenario of found) {
         const dir = dirname(scenario.file);
@@ -906,11 +951,11 @@ for (const domain of domains) {
         }
         for (const prefix of prefixes) {
             const owner = prefixOwners.get(prefix);
-            if (owner && owner !== dir) {
+            if (owner && owner !== base) {
                 report(dir, `префикс \`SC-${prefix}\` уже занят — \`${owner}\`; по номеру не видно, чей сценарий`);
                 continue;
             }
-            prefixOwners.set(prefix, dir);
+            prefixOwners.set(prefix, base);
         }
     }
 
@@ -1008,12 +1053,52 @@ const isProposedLaw = (file) => /^\*\*Статус:\*\*\s*предложен/m.t
     .filter(([law, file]) => !ruled.has(law) && !isProposedLaw(file))
     .forEach(([, file]) => report(file, 'у закона нет ни одного правила — заведи скил с `law:` на него'));
 
+/**
+ * Имена паттернов, которые дерево при раскладке пропустило: ключ `skip` в настройке проекта.
+ *
+ * Пропуск — выбор дерева, а не забытая работа: правило о процедурах бэкенда ложится и в дерево,
+ * где бэкенда нет вовсе. Требовать там паттерн значит требовать завести файл, которому нечего
+ * сказать, — и единственным способом позеленеть становится снятие пропуска.
+ */
+const skippedPatterns = () => {
+    const path = '.claude/rt-kit.json';
+    if (!exists(path)) {
+        return new Set();
+    }
+    try {
+        const skip = JSON.parse(read(path)).skip ?? [];
+
+        return new Set(skip.map((resource) => resource.match(/^patterns\/(.+)\.md$/)?.[1]).filter(Boolean));
+    } catch {
+        return new Set();
+    }
+};
+
+/**
+ * Раздел «Паттерны» самого правила — единственное место, где связь видна без файла паттерна:
+ * пропущенного файла в дереве нет, и поле `rule:` в нём спросить не у кого.
+ */
+// Флага `m` здесь нет намеренно: с ним `$` означает конец строки, и раздел кончается на первом
+// же переводе строки — пустым. Начало заголовка поэтому ищется своей парой, а не якорем.
+const PATTERNS_HEADING = /(?:^|\n)## Паттерны\n([\s\S]*?)(?=\n## |$)/;
+const patternsNamedBy = (text) => [...(text.match(PATTERNS_HEADING)?.[1] ?? '').matchAll(/^-\s+`([\w-]+)`/gm)].map(([, found]) => found);
+
+const skipped = skippedPatterns();
+
 for (const file of walk('.claude/skills', (name) => name === 'SKILL.md')) {
-    const head = frontMatterOf(read(file));
+    const text = read(file);
+    const head = frontMatterOf(text);
     const name = nameOf(head);
-    if (/^kind:\s*rule\s*$/m.test(head) && name && !patterned.has(name)) {
-        report(file, 'у правила нет ни одного паттерна — заведи скил с `rule:` на него');
+    if (!/^kind:\s*rule\s*$/m.test(head) || !name || patterned.has(name)) {
+        continue;
     }
+
+    const named = patternsNamedBy(text);
+    if (named.length > 0 && named.every((pattern) => skipped.has(pattern))) {
+        continue;
+    }
+
+    report(file, 'у правила нет ни одного паттерна — заведи скил с `rule:` на него');
 }
 
 checkTracedAnchors();

package/assets/checks/rt-kit-checks.config.mjs

@@ -71,6 +71,15 @@ const DEFAULTS = {
      * числе на каждой правке, а не о длине файла.
      */
     fileSizeLimit: 500,
+    /**
+     * Внешние пакеты, чьи перечисления считаются наравне с либами: своё перечисление под уже
+     * объявленный там набор — такая же копия, как и между двумя либами. Каждая запись — имя
+     * пакета и каталог объявлений внутри него; каталог ищется разрешением модуля, а не путём в
+     * `node_modules`: пакет, объявленный зависимостью подпроекта, в корне дерева не лежит вовсе,
+     * и зашитый путь на такой раскладке верным не бывает никогда. Пусто — внешние наборы не
+     * считаются.
+     */
+    externalEnums: [],
     /** Корни сквозных тестов; пусто — их в дереве нет. */
     e2eRoots: ['apps/site-e2e', 'apps/admin-e2e'],
     /** Корни бэкенда: у него нет ни компонентов, ни шаблонов, и часть признаков к нему не применяется. */

package/assets/commands/feedback.md

@@ -0,0 +1,95 @@
+---
+description: Слово о слое правил, сказанное посреди работы, ложится блоком в файл предложений
+argument-hint: '<что мешает, чего не хватило, что сработало не так>'
+---
+
+Положи слово пользователя блоком в файл предложений. Слово: `$ARGUMENTS`
+
+Зовётся **посреди работы**, а не после неё: то, обо что споткнулись час назад, к разбору закрытой
+задачи уже забыто, а сама реплика живёт до конца сессии и умирает вместе с ней. Разбор закрытой
+задачи смотрит на загруженное и на ход работы; реплик он не видит вовсе.
+
+Команда ничего не отправляет. Она кладёт блок на диск, а увозит его обычная отправка, позванная
+отдельно. Скажи об этом пользователю последней строкой — иначе положенное читается как
+отправленное, и он ждёт ответа, которого никто не посылал.
+
+## 1. Пойми, о чём слово
+
+Слово пользователя — проза: «вот это правило мешает», «гейт требует не то», «этого в правилах
+нет вовсе». Твоё дело — перевести её в три вещи:
+
+- **адрес** — куда правка идёт;
+- **ресурс** — что именно правится;
+- **готовый текст** — ровно то, что вставить.
+
+Адрес один из трёх, и выбирается он не по удобству:
+
+    пакет      — правка ресурса @rt-tools/agent-kit; верна любому дереву и уезжает наружу
+    компаньон  — implementation.md рядом с правилом: имена этого дерева и привязка статей
+    дерево     — надстройка этого дерева; наружу не уезжает никогда
+
+Ресурс называется идентификатором пакета — `rules/styling-bem.md`, `hooks/skill-gate.sh`,
+`patterns/git-workflow-commit.md`, — а у адресов «компаньон» и «дерево» путём в дереве.
+
+**Непонятный адрес спрашивается, а не назначается по догадке.** Неверный адрес уводит правку в
+чужой репозиторий: сказанное о своём дереве уезжает всем, а сказанное обо всех остаётся лежать
+дома. Пока пользователь не ответил, в файл не записывается ничего.
+
+Спрашивать не надо, когда адрес виден из самого слова: речь о правиле, которое ты только что
+грузил, — это `пакет`; речь об именах, путях и командах этого дерева — `компаньон` или `дерево`.
+
+## 2. Найди файл сегодняшнего дня
+
+Блок ложится туда же, куда его кладёт разбор закрытой задачи: у них один адресат и один формат, а
+второй файл рядом означал бы, что отправка читает два места, а пользователь не помнит, в каком
+лежит его слово.
+
+```bash
+ls .claude/rt-kit/proposals/$(date +%F)-*.md 2>/dev/null
+```
+
+Нашёлся — дописывай в него. Не нашёлся — заведи с образца, назвав по ветке:
+
+```bash
+mkdir -p .claude/rt-kit/proposals
+cp .claude/rt-kit/templates/proposal.md \
+   ".claude/rt-kit/proposals/$(date +%F)-$(git branch --show-current).md"
+```
+
+У свежего файла шапка образца остаётся, а незаполненный образец блока — `rules/<правило>.md` со
+скобками — заменяется твоим блоком: отправка такой образец пропускает, но лежит он молчаливым
+мусором.
+
+## 3. Напиши блок
+
+Форма заголовка — не украшение: по ней отправка отбирает то, что уезжает наружу. Блок без адреса
+в заголовке не уедет никуда и останется лежать молча.
+
+```markdown
+## <адрес> · <ресурс>
+
+- **место:** раздел «<заголовок>», в конец
+- **повод:** что в этой работе пошло не так без этого правила
+
+> Готовый текст правки — ровно то, что вставить, в стиле соседних правил: по-русски,
+> утверждением, без воды.
+```
+
+Повод пишется от случая, а не от желания: «здесь было неудобно» правилом не становится. Слово
+пользователя пересказывается его смыслом, а не твоими выводами о том, как надо было бы.
+
+**Адреса этого дерева в тексте блока не бывает** — ни пути, ни имени корня, ни имени чужого
+репозитория: файл уезжает в чужой репозиторий целиком. Найденный адрес отбивает отправку с
+номером строки, и это проверка, а не напоминание. Правь текст, а не обходи её.
+
+## 4. Скажи, что вышло
+
+Одной строкой: в какой файл лёг блок, сколько блоков в нём теперь и чем он уедет.
+
+```bash
+npx agent-kit propose --dry-run     # что уехало бы
+npx agent-kit propose               # отправить груз в приём
+```
+
+Отправка увозит блоки с адресом «пакет» и метит их отправленными; блоки «компаньон» и «дерево»
+остаются лежать — их правит тот, кто работает в этом дереве.

package/assets/commands/rules-review.md

@@ -0,0 +1,98 @@
+---
+description: Смысловое ревью семьи текстов слоя правил — закон, его правила и паттерны при них
+argument-hint: '<имя закона>'
+---
+
+Прогони смысловое ревью одной семьи текстов пакета правил. Семья: `$ARGUMENTS`
+
+Зовётся **в репозитории самого пакета**, а не в дереве, где он стоит: судятся исходные тексты
+ресурсов, и лежат они только здесь. В чужом дереве лежит разложенная копия выбранных ресурсов, а
+не семья целиком, и путей, по которым команда ходит, в нём нет вовсе: обход по ним вернёт
+пустоту, неотличимую от «такого закона не бывает». Каталог ресурсов ниже назван так, как он
+зовётся в репозитории пакета.
+
+Считаемое ловит проверка полноты текстов — недостающий раздел, правило без паттерна, имя соседа,
+которому в наборе ничего не отвечает. Здесь ищется то, чего она не считает: два текста,
+говорящих об одном разное, и случай, которого не назвал ни один. Ответ роли не повторяется от
+запуска к запуску, поэтому в гейт он не идёт и ветку не отбивает.
+
+## 1. Пойми, какая семья
+
+Семья зовётся именем закона — без пути и без расширения: `work-conduct`, `delivery`,
+`project-documentation`.
+
+```bash
+ls projects/agent-kit/assets/laws/*.md projects/agent-kit/assets/laws/*/*.md
+```
+
+**Имени нет** — назови человеку перечень имён и остановись. Догадываться по похожести нельзя:
+ревью уйдёт на чужую семью, и его находки человек примет за находки о своей.
+
+**Названо несколько** — гони по одной, по очереди, и ответы не смешивай: находка семьи читается
+вместе с её законом, а сваленные в кучу они теряют адрес.
+
+**Довода нет вовсе** — потребуй имя и напечатай перечень. Умолчания здесь нет: «первый
+попавшийся закон» даёт прогон, неотличимый от осмысленного.
+
+**Закон лежит в слое приложения** — это законный случай, а не промах: у денег, локалей и доступа
+семья такая же. Читается он оттуда же, где лежит.
+
+## 2. Собери семью
+
+Правило принадлежит закону полем `law:`, паттерн правилу — полем `rule:`. Приставка имени
+ненадёжна: её несут не все паттерны.
+
+```bash
+LAW=<имя закона>
+grep -l "^law: $LAW\$" projects/agent-kit/assets/rules/*.md
+```
+
+Дальше по каждому найденному правилу — его паттерны. Имя правила для поиска берётся голым: без
+вида и без требования — оба стоят суффиксами в имени файла, а поле `rule:` у паттерна несёт
+только само имя.
+
+```bash
+RULE=<имя правила: первое слово имени файла, до первой точки>
+grep -l "^rule: $RULE\$" projects/agent-kit/assets/patterns/*.md
+```
+
+**Виды берутся все.** `git-workflow.github`, `git-workflow.gitlab`, `git-workflow.azure` — три
+редакции одного правила: дерево раскладывает одну, а расходятся они молча.
+
+**Суффикс требования — не вид.** `entity-conventions.needs-admin`, `observability.needs-app` —
+это правила, которые дерево берёт, только когда объявило нужную черту. Имя с этим суффиксом в
+поле `rule:` не стоит ни у одного паттерна: поиск по нему возвращает пустоту, и семья уезжает в
+ревью без паттернов вовсе — молча, потому что пустой ответ выглядит как «паттернов нет».
+
+**У закона нет ни одного правила** — скажи это человеку и остановись. Читать один закон нечем:
+расхождение живёт между двумя текстами, а пробел уровня статьи без правил под ней — не находка
+ревью, а отсутствие целого слоя. Сам по себе такой закон стоит разговора: его находит и проверка
+полноты текстов, и она же скажет, сколько их.
+
+## 3. Запусти роль
+
+Инструментом `Agent`, `subagent_type: 'rules-reviewer'`. В промпт — имя закона и полный список
+путей: закон, все его правила со всеми видами, все паттерны при них. Список собираешь ты: роль
+git-команд не зовёт и историю не читает.
+
+Одна роль на семью. Веер из нескольких ролей со сведением ответов здесь не заводится: взгляд на
+предмет один — два текста об одном говорят разное, — а сведение превращает дословные цитаты в
+пересказ.
+
+## 4. Покажи находки человеку
+
+**Как есть.** Роль возвращает цитаты дословно, и пересказ их портит: по пересказу человек не
+отличит настоящее расхождение от прочтения роли.
+
+Порядок сохрани: сперва расхождения — у каждого два места и две цитаты, — потом пробелы, у
+которых второго места нет.
+
+По каждой находке скажи своё: согласен или нет и почему. Правку не вноси — тексты правил
+действуют на все будущие сессии всех деревьев, и решает по ним человек.
+
+Находка, с которой человек согласился, идёт дальше двумя путями, и выбирает он:
+
+- **правится тут же** — если это правка текста пакета и она укладывается в текущую работу;
+- **уходит задачей** в очередь работ — если тянет за собой код, раскладку или другой закон.
+
+Пустой ответ роли — тоже результат: скажи, что находок нет, и не выдумывай их из вежливости.