@rt-tools/agent-kit 0.8.2 → 0.9.0

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` во вступлении
 файла. Скил без закона стоит рядом с лестницей, а не в ней: он не про то, что должно быть верно
@@ -292,6 +293,18 @@ npx agent-kit propose --dry-run   # что уехало бы
 npx agent-kit propose             # отправить груз в приём
 ```
 
+Чтобы грузу было чем представиться, у дерева должен быть токен. Выдаётся он один раз — по
+приглашению, которое владелец приёма выписал этому дереву:
+
+```bash
+npx agent-kit enroll --code <код приглашения>   # завести дерево и положить его токен
+```
+
+Код одноразовый и годен ограниченное время; имя дерева называет приглашение, а не обращение.
+Токен ложится в файл, названный ключом `token`, правами «читает только владелец файла»; лежащий
+токен команда молча не перезаписывает — для этого есть довод `--force`. Адрес приёма без TLS
+команда отбивает у себя, не доходя до сети: токен уходит единственным ответом на обращение.
+
 Груз уезжает при каждом прогоне тремя родами: **сводка наблюдений со снимком надстроек**,
 **предложения** с адресом «пакет» — когда они есть — и **разборы происшествий**. Прогон без
 замечаний тоже говорит, чем пользовались, чем не пользовались ни разу и что дерево

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/board.github.mjs

@@ -203,8 +203,55 @@ export function fetchIssue(number, options) {
     }
 }
 
+/**
+ * Вершина берётся вместе с остальным: спросить её потом значило бы второй вызов на каждый PR,
+ * а судят по ней и папку задачи, и прогон.
+ */
 export function fetchOpenPulls(options) {
-    return ghJson(['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,title,headRefName,body'], options);
+    return ghJson(
+        ['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,title,headRefName,headRefOid,isDraft,body'],
+        options
+    );
+}
+
+/**
+ * Сколько прогонов завелось на этой вершине.
+ *
+ * Спрашивается вершина, а не ветка: прогон промежуточного коммита о состоянии вершины не
+ * говорит ничего, а список прогонов ветки отдаёт их вперемешку.
+ */
+export function runsOnHead(sha, options) {
+    const answer = gh(['api', `repos/${OWNER}/${REPO}/actions/runs?head_sha=${sha}&per_page=1`, '--jq', '.total_count'], options);
+    return Number(String(answer).trim());
+}
+
+/**
+ * Чем кончились прогоны на этой вершине: `success`, если все завершились успехом, `running`,
+ * если хоть один ещё идёт, `failure` — если хоть один упал. Прогонов нет вовсе — `none`.
+ *
+ * Цвет спрашивается отдельно от факта: факт отвечает на вопрос «событие дошло», цвет — на
+ * вопрос «работу можно отдавать». Второй вопрос задаётся там, где готовое стоит черновиком.
+ */
+export function verdictOnHead(sha, options) {
+    const answer = gh(
+        [
+            'api',
+            `repos/${OWNER}/${REPO}/actions/runs?head_sha=${sha}&per_page=20`,
+            '--jq',
+            '[.workflow_runs[] | {status, conclusion}] | if length == 0 then "none"' +
+                ' elif any(.status != "completed") then "running"' +
+                ' elif any(.conclusion != "success") then "failure"' +
+                ' else "success" end',
+        ],
+        options
+    );
+    return String(answer).trim();
+}
+
+/** Когда вершина легла в ветку — по времени коммита у хостинга, а не по местным часам ветки. */
+export function headCommittedAt(sha, options) {
+    const answer = gh(['api', `repos/${OWNER}/${REPO}/commits/${sha}`, '--jq', '.commit.committer.date'], options);
+    return Date.parse(String(answer).trim());
 }
 
 /** `[<КЛЮЧ>-<номер>]` в начале заголовка — единственная форма номера в названиях */

package/assets/checks/check-board.github.mjs

@@ -19,12 +19,16 @@
  * Момент, когда задачу берут в работу, отсюда не виден вовсе — ветки на борде нет, —
  * и «In progress» здесь не требуется ни от кого.
  *
+ * Прогон на вершине спрашивает тоже она: страница PR без прогона выглядит так же, как
+ * страница с зелёным, — цвета у неё нет ни там, ни там, — и вершина, за которой прогон
+ * не встал, узнаётся только тем, что кто-то открыл список прогонов руками.
+ *
  * Нет сети или нет токена — код возврата ноль: проверка, падающая в самолёте,
  * перестаёт что-либо значить.
  *
  * Ненулевой код возврата и перечень расхождений.
  */
-import { statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
@@ -39,9 +43,12 @@ import {
     fetchIssues,
     fetchOpenPulls,
     gh,
+    headCommittedAt,
     numberFromTaskDir,
     numberFromTitle,
+    runsOnHead,
     taskDirs,
+    verdictOnHead,
 } from './board.mjs';
 import { CONFIG, ROOT } from './rt-kit-checks.config.mjs';
 
@@ -49,6 +56,17 @@ const IN_REVIEW = STATUS_OPTIONS[IN_REVIEW_STATUS].name;
 const TASKS_DIR = join(ROOT, CONFIG.tasksDir);
 /** Возраст брошенного черновика, после которого он перестаёт выглядеть начатым сегодня. */
 const DRAFT_DAYS = 7;
+/**
+ * Сколько времени вершине даётся на то, чтобы прогон за ней встал. Событие доходит до хостинга
+ * не мгновенно, и сверка, позванная сразу после пуша, иначе краснела бы на здоровой ветке.
+ */
+const RUN_GRACE_MINUTES = 10;
+/**
+ * Конвейер дерева. Прогоны спрашиваются только там, где ему есть откуда взяться: дерево без
+ * конвейера получило бы строку на каждый открытый PR, и не о чём.
+ */
+const PIPELINE = CONFIG.pushGate?.pipelineFile ?? '';
+const HAS_PIPELINE = PIPELINE !== '' && existsSync(join(ROOT, PIPELINE));
 
 const problems = [];
 const report = (message) => problems.push(message);
@@ -104,6 +122,62 @@ function folderInBranch(branch, options) {
     }
 }
 
+/**
+ * Прогон на вершине открытого PR.
+ *
+ * Молчание страницы и зелёный прогон читаются одинаково, а событие до хостинга доходит не
+ * всегда: в час его отказов пуш прошёл, а прогона за ним не встало. Сверка называет такую
+ * вершину, пока PR ещё открыт, — после слияния об этом узнавать поздно.
+ *
+ * Считается сам факт прогона, а не его цвет. Идущий и упавший прогон видны на странице PR оба;
+ * невидимо только отсутствие, и говорит сверка ровно о нём.
+ *
+ * Свежая вершина не судится: между пушем и прогоном проходит время, и красная строка на этом
+ * промежутке значила бы «подожди», а не «чини».
+ */
+function checkHeadRun(pull, options) {
+    if (runsOnHead(pull.headRefOid, options) > 0) {
+        checkReadyDraft(pull, options);
+        return;
+    }
+
+    const minutes = Math.floor((Date.now() - headCommittedAt(pull.headRefOid, options)) / 60000);
+    if (minutes < RUN_GRACE_MINUTES) {
+        return;
+    }
+
+    report(
+        `PR #${pull.number}: на вершине ${pull.headRefOid.slice(0, 8)} прогона нет, а лежит она ${minutes} мин — ` +
+            `конвейер события не получил; верни его новым коммитом либо перезакрытием PR ` +
+            `(gh pr close ${pull.number} && gh pr reopen ${pull.number})`
+    );
+}
+
+/**
+ * Готовая работа, оставленная черновиком.
+ *
+ * У черновика кнопка слияния заблокирована самим хостингом, поэтому зелёная страница PR
+ * владельцу ничего не разрешает: список, в котором всё серое, читается как «работа не сделана».
+ * Гард снятия черновика сюда не достаёт — он судит один ход и молчит, пока ветка везёт папку
+ * своей задачи; сверка же смотрит на состояние очереди целиком.
+ *
+ * Четыре PR так и простояли черновиками двое суток — разбор
+ * `docs/postmortems/2026-08-18-ready-work-left-in-drafts.md`.
+ */
+function checkReadyDraft(pull, options) {
+    if (pull.isDraft !== true) {
+        return;
+    }
+    if (verdictOnHead(pull.headRefOid, options) !== 'success') {
+        return;
+    }
+
+    report(
+        `PR #${pull.number}: прогон на вершине ${pull.headRefOid.slice(0, 8)} зелёный, а PR черновик — ` +
+            `разбери папку задачи и сними черновик (gh pr ready ${pull.number}) либо скажи владельцу, чего ждёшь`
+    );
+}
+
 let checked = { issues: 0, pulls: 0 };
 
 // Черновики судятся по диску и потому проверяются всегда: связи для этого не нужно.
@@ -160,6 +234,10 @@ try {
         // сверка обязана назвать ДО слияния: гард судит её на слиянии, а слияние нажимает
         // человек в браузере, где хуков нет вовсе. Сказанная после, эта строка уже не чинится
         // тем же PR — работа перешла дальше, и на разбор заводится вторая задача.
+        if (HAS_PIPELINE && pull.headRefOid) {
+            checkHeadRun(pull, options);
+        }
+
         if (!FOLDER_SKIP.test(String(pull.body ?? '')) && pull.headRefName) {
             const folder = folderInBranch(pull.headRefName, options);
             if (folder !== null) {
@@ -210,6 +288,11 @@ try {
     }
 }
 
+// Непроверенное называется вслух: молчание о прогонах читалось бы как «прогоны на месте».
+if (!offline && !HAS_PIPELINE) {
+    console.log('check-board: прогоны на вершинах не спрашивались — файла конвейера в дереве нет');
+}
+
 if (problems.length > 0) {
     console.error(`check-board: расхождений ${problems.length}\n`);
     problems.forEach((problem) => console.error(`  ${problem}`));

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}`);
         }
     }
 }