@rt-tools/agent-kit 0.5.0 → 0.5.2

package/README.md

@@ -26,6 +26,7 @@ npx agent-kit init      # спросить законы галочками и з
 npx agent-kit sync      # разложить выбранное в docs/constitution/
 npx agent-kit doctor    # что разложено, что отстало, чего не хватает
 npx agent-kit adopt     # отдать пакету файлы, лежащие на его путях не от него
+npx agent-kit stats     # чем пользовались, чем ни разу, обо что спотыкались
 ```
 
 `init` называет и то, чего пакет ждёт от дерева: значения дырок, которые придётся вписать в
@@ -238,6 +239,73 @@ npx agent-kit init --laws access,delivery,verifiability
 
 Отказ хотя бы по одному файлу не пишет ничего: половина разложенного хуже целого.
 
+## Наблюдения и сводка
+
+Правило, которого никто не открывает, не действует, — и узнать об этом было нечем. Гарды пишут
+наблюдения: правило загружено, гейт отбил правку, гард отказал. Строка несёт имя ресурса пакета,
+род события, род правки, версию и признак сессии; путей дерева, имён его доменов и имени его
+самого в ней нет — значение со слэшем не пишется вовсе.
+
+```bash
+npx agent-kit stats --days 3     # за отрезок; без довода — за три дня
+npx agent-kit stats --json       # то же машиночитаемо
+```
+
+Самая ценная строка сводки — не «чем пользовались», а **что разложено и не загружено ни разу**:
+чем пользуются, видно и по работе, а мёртвый ресурс ничем себя не выдаёт.
+
+Наблюдения лежат в `.claude/rt-kit/observations/` файлом на день и снимаются через тридцать
+дней. Запись выключается ключом `"observe": false` в конфиге — целиком, а не частями. Каталог
+просится в список игнорируемого; вписывает его проект — в чужие файлы дерева пакет не пишет.
+
+## Предложения обратно в пакет
+
+Разбор закрытой задачи и раньше ставил каждому предложению адрес — «пакет», «компаньон» или
+«дерево», — но результат оставался в переписке, и правки переносили руками. Теперь предложения
+ложатся файлом в `.claude/rt-kit/proposals/`, блоком на предложение:
+
+```markdown
+## пакет · rules/styling-bem.md
+
+- **место:** раздел «Ловушки», в конец
+- **повод:** что в этой задаче пошло не так без этого правила
+
+> Готовый текст правки.
+```
+
+```bash
+npx agent-kit propose --dry-run   # что уехало бы
+npx agent-kit propose             # завести записи в очереди работ пакета
+```
+
+Наружу уезжает **только адрес «пакет»** и вместе с ним — сводка наблюдений: без цифр
+предложение читается как мнение. Отправленное помечается ссылкой в том же файле и второй раз не
+уезжает. Куда отправлять, пакет берёт из своего манифеста, а не из зашитого в код адреса.
+
+Перед отправкой текст сверяется на адрес дерева — абсолютный путь, имя корня, адрес удалённого
+репозитория. Нашлось — отказ с номером строки, и отбивается вся отправка целиком: «уехало два из
+трёх» читается как «всё в порядке». Файл уезжает в чужой репозиторий, и запрет называть чужое
+дерево держится проверкой, а не памятью того, кто пишет.
+
+### Что для этого нужно
+
+Своего сервера у механизма нет, ключей и учётных записей он не заводит. Наблюдения и сводка
+живут целиком на машине; в сеть ходит только отправка, и только по команде человека.
+
+| Где | Что нужно |
+| --- | --- |
+| у потребителя | `jq` — его требуют и сами гарды |
+| у потребителя | помощник хостинга, вошедший в любую учётную запись: запись заводится от её имени |
+| в репозитории пакета | метка, по которой сведение находит предложения, — заводится один раз |
+
+```bash
+gh label create agent-kit-feedback --description 'Предложение по слою правил, пришедшее из дерева'
+```
+
+Метки нет — отправка отказывает, и понять причину по сообщению помощника нельзя: про метку,
+доступ и собственное отсутствие он говорит одинаково глухо. Поэтому отказ команды называет все
+три сам.
+
 ## Роли и конвейеры
 
 Пакет везёт шесть ролей субагентов и два конвейера из них.
@@ -260,6 +328,11 @@ npx agent-kit init --laws access,delivery,verifiability
 `skill-curator` приезжает и слеш-командой: она собирает сводку о задаче и список загруженных
 правил, без которых разбор выродится в пересказ.
 
+Вторая команда, `next-session`, закрывает заход: приводит дерево к главной ветке — переходом на
+неё, если работа шла по правилу и отчёт влит, и вливанием в текущую ветку во всех прочих
+случаях, — снимает влитые локальные ветки, называет невлитые и пишет передачу для следующего
+захода. Незакоммиченная правка её останавливает до первого действия; поставки она не касается.
+
 ## Как этим пользуются в дереве
 
 Всё, что выше, пакет объясняет человеку. Агенту то же самое объясняет скил `agent-kit` —

package/assets/checks/check-doc-paths.mjs

@@ -1,19 +1,28 @@
 #!/usr/bin/env node
 /**
- * Проверка того, что пути, названные в документации, существуют.
+ * Проверка того, что адреса, названные в документации, существуют.
  *
  * Документ, ссылающийся на исчезнувший файл, хуже отсутствующего: он выглядит
  * действующей справкой и уводит читателя в каталог, которого нет. Накапливается
  * это молча — перекладка дерева правит код и ломает текст, а текст никто не
- * собирает. К моменту заведения проверки из 159 путей, названных в `docs/`,
- * не существовало 80.
+ * собирает.
  *
- * Считаются только пути в обратных кавычках и вне блоков кода: в блоках лежат
- * команды и вывод, где `dist/apps/api/main.js` — результат сборки, а не файл
- * репозитория. Шаблоны (`*`, `<…>`, `{…}`) пропускаются: это форма пути, а не путь.
+ * Считаются только адреса в обратных кавычках и вне блоков кода: в блоках лежат
+ * команды и вывод, где путь до собранного — результат сборки, а не файл
+ * репозитория. Шаблоны (`*`, `<…>`, `{…}`) пропускаются: это форма адреса, а не адрес.
  *
- * Документы, которые по устройству говорят о несуществующем — планы будущего и
- * архив, — перечислены в tools/doc-paths-allowlist.json.
+ * Адрес бывает трёх родов, и все три судятся одинаково: укоренённый в дереве путь,
+ * голое имя файла и каталог. Каталогами занята половина таблиц «Где это лежит», и
+ * проверка, знающая только строку с расширением, их не видит вовсе.
+ *
+ * Документы, которые по устройству говорят о несуществующем — планы будущего, архив
+ * и папки задач, — из проверки выведены. Там же переносимый текст: его адреса
+ * принадлежат тому дереву, куда правило ложится, и в этом они примеры, а не ссылки.
+ *
+ * Вторым заходом сверяется полнота указателя каталога: обзорный документ перечисляет
+ * записи таблицей, и читатель ищет по ней, а не обходом. Это обратная сторона той же
+ * договорённости — не только адрес из текста ведёт в файл, но и файл назван в тексте,
+ * по которому его ищут.
  *
  * Ненулевой код возврата и перечень расхождений.
  */
@@ -24,20 +33,47 @@ import { join } from 'node:path';
 import { allowlistOf, CONFIG, ROOT } from './rt-kit-checks.config.mjs';
 
 const ALLOWLIST = allowlistOf('doc-paths');
-// `worktrees` — копии репозитория под `.claude/`: их документы описывают раскладку своей
-// ветки, а проверка ищет пути в дереве текущей. Одна брошенная копия дала 73 расхождения и
-// красный сквозной прогон на ветке, которая её не заводила.
+// `worktrees` — копии репозитория под каталогом агента: их документы описывают раскладку
+// своей ветки, а проверка ищет адреса в дереве текущей. Одна брошенная копия дала 73
+// расхождения и красный сквозной прогон на ветке, которая её не заводила.
 const SKIPPED_DIRS = CONFIG.skippedDirs;
 /**
- * Архив описывает раскладку, бывшую на момент записи. Править в нём пути — значит
+ * Архив описывает раскладку, бывшую на момент записи. Править в нём адреса — значит
  * переписывать историю задним числом, поэтому он выведен из проверки целиком.
  */
 const ARCHIVE_DIR = CONFIG.archiveDir;
-/** Расширения, по которым строка в кавычках считается путём, а не именем сущности */
+/**
+ * Папка задачи описывает ход работы, и снятое она называет по имени: раздел находок
+ * перечисляет ровно то, чего в дереве нет. Отличить такое упоминание от ссылки машине
+ * нечем, а живёт папка до слияния — поэтому она выведена из проверки, как архив.
+ */
+const TASKS_DIR = CONFIG.tasksDir.endsWith('/') ? CONFIG.tasksDir : `${CONFIG.tasksDir}/`;
+/**
+ * Каталоги, чей указатель сверяется с содержимым. Каталог, выведенный из проверки адресов,
+ * иначе не судит ничто: запись, приехавшая слиянием соседней ветки, остаётся неназванной, а
+ * читатель ищет по указателю. Сверенный руками указатель расходится снова через сутки.
+ */
+const INDEXED_DIRS = (CONFIG.indexedDirs ?? []).map((dir) => (dir.endsWith('/') ? dir : `${dir}/`));
+/**
+ * Исходники переносимых текстов: правило, которое ложится в другое дерево, называет адреса
+ * того дерева. Разложенная копия узнаётся по шапке, а исходник шапки не несёт — её ставит
+ * раскладка, — поэтому его каталог называется настройкой.
+ */
+const PORTABLE_DIRS = (CONFIG.portableDirs ?? []).map((dir) => (dir.endsWith('/') ? dir : `${dir}/`));
+/** Шапка разложенного файла: версия пакета, ресурс и сумма тела. */
+const STAMP_LINE = /rt-kit\s+v\S+\s+·\s+\S+\s+·\s+[0-9a-f]{12}/;
+/** Шапка встаёт первой строкой тела, а тело начинается после вступления скила. */
+const STAMP_LOOKAHEAD = 12;
+/** Расширения, по которым голое имя считается файлом, а не именем сущности */
 const EXTENSIONS = 'ts|mts|cts|js|mjs|cjs|json|jsonc|scss|css|html|proto|conf|ya?ml|sh|md|sql|txt|xml|svg|webp|png|ico|env|Dockerfile|lock';
-const PATH_IN_BACKTICKS = new RegExp(`\`([^\`\\n]+?\\.(?:${EXTENSIONS}))\``, 'g');
+/**
+ * Берётся любая строка в кавычках: каталог расширения не несёт, и требовать его в самой
+ * выборке значило бы не видеть половину таблиц «Где это лежит». Отсев — в `looksLikePath`.
+ */
+const PATH_IN_BACKTICKS = /`([^`\n]+?)`/g;
 
 const problems = [];
+const indexProblems = [];
 const report = (doc, line, path) => problems.push(`${doc}:${line}: нет файла \`${path}\``);
 
 function readAllowlist() {
@@ -71,9 +107,9 @@ function collectDocs(dir = '.') {
 
 /**
  * Документы, которые в репозиторий не попадут: личный черновик, лежащий в дереве и
- * закрытый `.gitignore` или `.git/info/exclude`. Проверка судит репозиторий, а не рабочий
- * стол того, кто её запустил: мёртвая ссылка в чужом черновике держала гейт пуша, хотя ни
- * в одну ветку этот файл не едет.
+ * закрытый настройкой неотслеживаемого. Проверка судит репозиторий, а не рабочий стол того,
+ * кто её запустил: мёртвая ссылка в чужом черновике держала гейт пуша, хотя ни в одну ветку
+ * этот файл не едет.
  */
 function droppedByGit(docs) {
     if (docs.length === 0) {
@@ -91,12 +127,7 @@ function droppedByGit(docs) {
     return new Set((ignored.stdout ?? '').split('\n').filter(Boolean));
 }
 
-/**
- * Верхний уровень дерева. Проверяются только адреса, укоренённые в нём: `src/index.ts`
- * в правиле означает «любой файл такого вида», а `services/theme/theme.service.ts` —
- * обрывок чужого пути. Ни то, ни другое адресом не является, и требовать их
- * существования значит ловить форму записи вместо ссылки.
- */
+/** Верхний уровень дерева: по нему узнаётся адрес, укоренённый в репозитории */
 const ROOTED_IN = new Set(
     readdirSync(ROOT, { withFileTypes: true })
         .filter((entry) => entry.isDirectory() && !SKIPPED_DIRS.includes(entry.name))
@@ -104,18 +135,138 @@ const ROOTED_IN = new Set(
 );
 
 /**
- * Путь ли это вообще. Отсекается всё, что описывает форму, а не адрес: шаблоны,
- * URL и пакеты npm.
+ * Дерево спрашивается у системы контроля версий, а не обходом каталогов: каталоги агента и
+ * конвейера начинаются с точки, и обход мимо них проходит молча — всё, что в них лежит,
+ * читалось бы как несуществующее. Неотслеживаемое берётся вместе с отслеживаемым: файл,
+ * заведённый этой же веткой и ещё не добавленный, существует ничуть не меньше.
+ */
+function treeOfRepo() {
+    const listed = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const paths = (listed.stdout ?? '').split('\n').filter(Boolean);
+    const files = new Set(paths);
+    const dirs = new Set();
+    const byName = new Map();
+
+    for (const path of paths) {
+        const segments = path.split('/');
+        for (let depth = 1; depth < segments.length; depth += 1) {
+            dirs.add(segments.slice(0, depth).join('/'));
+        }
+        byName.set(segments[segments.length - 1], true);
+    }
+    for (const dir of dirs) {
+        byName.set(dir.split('/').pop(), true);
+    }
+
+    return { files, dirs, byName };
+}
+
+const TREE = treeOfRepo();
+
+/**
+ * Адрес ли это вообще. Отсекается всё, что описывает форму, а не адрес: шаблоны, сетевые
+ * ссылки, имена пакетов, флаги и привязка «путь:символ» — её судит сверка спеков. Дальше
+ * кандидат бывает двух родов: укоренённый в дереве и голое имя. Голым именем зовут и файл, и
+ * каталог — оба ищутся по дереву, потому что адрес у них один, а написан он коротко.
  */
 function looksLikePath(candidate) {
     if (/[*<>{}$|\s]|\.\.\.|…/.test(candidate)) {
         return false;
     }
-    if (/^(https?:|@|~|\/)/.test(candidate)) {
+    if (/^(https?:|@|~|\/|-)/.test(candidate) || candidate.includes(':')) {
+        return false;
+    }
+    // Каталог, который проверка не обходит, она и не судит: там чужое, сборка и служебное
+    if (SKIPPED_DIRS.some((dir) => candidate.startsWith(`${dir}/`))) {
+        return false;
+    }
+    // Начинается с точки и стоит без каталога — род файла, а не файл
+    if (/^\.[^/]+$/.test(candidate)) {
         return false;
     }
 
-    return ROOTED_IN.has(candidate.split('/')[0]);
+    return candidate.includes('/') || new RegExp(`\\.(?:${EXTENSIONS})$`).test(candidate);
+}
+
+/**
+ * Есть ли такой адрес в дереве. Укоренённый спрашивается у файловой системы: он назван
+ * целиком, и промах в нём — промах. Голое имя ищется по дереву целиком — и среди файлов, и
+ * среди каталогов: имя каталога в обзорном документе либы означает каталог рядом, а не
+ * каталог в корне.
+ */
+function existsInTree(candidate) {
+    const bare = candidate.replace(/\/$/, '');
+
+    if (ROOTED_IN.has(bare.split('/')[0])) {
+        return existsSync(join(ROOT, bare));
+    }
+    if (TREE.files.has(bare) || TREE.dirs.has(bare)) {
+        return true;
+    }
+    if (bare.includes('/')) {
+        return [...TREE.files, ...TREE.dirs].some((path) => path.endsWith(`/${bare}`));
+    }
+
+    return TREE.byName.has(bare);
+}
+
+/**
+ * Переносимый текст: разложенный пакетом — по шапке, его исходник — по каталогу из настройки.
+ * Адреса в нём принадлежат тому дереву, куда правило ложится: `libs/common/util` в дереве,
+ * которое зовёт свои корни иначе, — не мёртвая ссылка, а пример. Судить их здесь значит
+ * краснеть на полтораста строк, ни одна из которых не чинится правкой этого дерева.
+ */
+function isPortable(doc) {
+    if (PORTABLE_DIRS.some((dir) => doc.startsWith(dir))) {
+        return true;
+    }
+
+    return readFileSync(join(ROOT, doc), 'utf8')
+        .split('\n', STAMP_LOOKAHEAD)
+        .some((line) => STAMP_LINE.test(line));
+}
+
+/** Из проверки адресов выведены документы, которые по устройству говорят о несуществующем. */
+const isSkipped = (doc) => doc.startsWith(ARCHIVE_DIR) || doc.startsWith(TASKS_DIR) || isPortable(doc);
+
+/**
+ * Полнота указателя каталога: у каждой записи каталога есть строка в таблице, у каждой
+ * строки — запись. Записью считается первое имя в обратных кавычках строки таблицы: во
+ * второй колонке стоит проза, и брать оттуда было бы нечего. Каталог берётся у системы
+ * контроля версий той же выборкой, что и дерево: черновик, закрытый настройкой
+ * неотслеживаемого, в репозиторий не едет и указателю не нужен.
+ */
+function checkIndex(dir) {
+    const index = `${dir}README.md`;
+    if (!existsSync(join(ROOT, index))) {
+        return;
+    }
+
+    const named = new Set(
+        readFileSync(join(ROOT, index), 'utf8')
+            .split('\n')
+            .filter((line) => line.startsWith('|'))
+            .map((line) => line.match(PATH_IN_BACKTICKS)?.[0].replaceAll('`', ''))
+            .filter((name) => name?.endsWith('.md'))
+    );
+    const stored = new Set(
+        [...TREE.files]
+            .filter((path) => path.startsWith(dir) && path.endsWith('.md') && path !== index)
+            .map((path) => path.slice(dir.length))
+    );
+
+    [...stored]
+        .filter((name) => !named.has(name))
+        .sort()
+        .forEach((name) => indexProblems.push(`${index}: запись \`${name}\` лежит в каталоге, но в таблице не названа`));
+    [...named]
+        .filter((name) => !stored.has(name))
+        .sort()
+        .forEach((name) => indexProblems.push(`${index}: строка \`${name}\` названа в таблице, но записи в каталоге нет`));
 }
 
 function checkDoc(doc, allowed) {
@@ -136,27 +287,46 @@ function checkDoc(doc, allowed) {
             if (!looksLikePath(candidate) || allowed.has(candidate)) {
                 continue;
             }
-            if (!existsSync(join(ROOT, candidate))) {
+            if (!existsInTree(candidate)) {
                 report(doc, index + 1, candidate);
             }
         }
     });
 }
 
+/** Расхождение указателя печатается своим списком: чинится оно строкой в таблице, а не молчанием. */
+function reportIndex() {
+    if (indexProblems.length === 0) {
+        return;
+    }
+
+    console.error(`\nуказатель разошёлся с каталогом, расхождений ${indexProblems.length}\n`);
+    indexProblems.forEach((problem) => console.error(`  ${problem}`));
+    console.error(
+        '\nЗапись называется в таблице указателя тем же изменением, которым кладётся:\nчитатель ищет по указателю, а не обходом каталога.'
+    );
+}
+
 const allowlist = readAllowlist();
 const allowedPaths = new Set(allowlist.paths);
-const collected = collectDocs().filter((doc) => !allowlist.files.includes(doc) && !doc.startsWith(ARCHIVE_DIR));
+const collected = collectDocs().filter((doc) => !allowlist.files.includes(doc) && !isSkipped(doc));
 const dropped = droppedByGit(collected);
 const docs = collected.filter((doc) => !dropped.has(doc));
 
 docs.forEach((doc) => checkDoc(doc, allowedPaths));
+INDEXED_DIRS.forEach((dir) => checkIndex(dir));
 
 if (problems.length > 0) {
     console.error(`check-doc-paths: расхождений ${problems.length}\n`);
     problems.forEach((problem) => console.error(`  ${problem}`));
     console.error(
-        `\nЛибо путь устарел и его надо поправить, либо документ описывает ещё не созданное —\nтогда он вносится в ${ALLOWLIST}.`
+        `\nЛибо адрес устарел и его надо поправить, либо документ описывает ещё не созданное —\nтогда он вносится в ${ALLOWLIST}.`
     );
+}
+
+reportIndex();
+
+if (problems.length > 0 || indexProblems.length > 0) {
     process.exit(1);
 }
 

package/assets/checks/check-specs.mjs

@@ -62,14 +62,20 @@ const TEST_ROOTS = CONFIG.sourceRoots;
 const SOURCE_ROOTS = [...CONFIG.sourceRoots, ...(CONFIG.schemaFile ? [CONFIG.schemaFile.split('/')[0]] : [])];
 const SKIPPED_DIRS = CONFIG.skippedDirs;
 
-/** `### SC-BK-03 — заявка на занятые даты` */
-const SCENARIO_HEADING = /^###\s+(SC-([A-Z]{2,4})-(\d{2,3}))\s+—\s+(.+?)\s*$/;
+/**
+ * `### SC-BK-03 — заявка на занятые даты`
+ *
+ * Номер принимается от одной цифры до трёх. Заголовок, не подошедший под шаблон, сценария не
+ * заводит и отказа не даёт: дерево, пронумеровавшее сценарии с единицы, теряло бы первые
+ * девять из них молча — ни в покрытии, ни в долгах, при зелёной сверке.
+ */
+const SCENARIO_HEADING = /^###\s+(SC-([A-Z]{2,4})-(\d{1,3}))\s+—\s+(.+?)\s*$/;
 /** Отметка осознанно непокрытого сценария; причина обязательна */
 const UNCOVERED = /^Не покрыто:\s*\S/;
 /** Тест есть, но проверяет не всё обещанное или идёт другим путём */
 const PARTIAL = /^Покрытие:\s*частичное\s*—\s*\S/;
-/** Упоминание сценария в заголовке теста */
-const SCENARIO_REFERENCE = /\bSC-[A-Z]{2,4}-\d{2,3}\b/g;
+/** Упоминание сценария в заголовке теста; номер той же длины, что и в заголовке сценария */
+const SCENARIO_REFERENCE = /\bSC-[A-Z]{2,4}-\d{1,3}\b/g;
 /** Строка обещания сценария; её продолжения идут с отступом */
 const PROMISE = /^Тогда\s+\S/;
 /**
@@ -229,7 +235,34 @@ function ruleHeadOf(bulletText) {
  * Одно слово в двух смыслах развели именно здесь: «правило» — слой между законом и скилом,
  * а внутри закона живут статьи.
  */
-function checkRuleImplementation(specFile, text, mapFile, heading = '## Правила') {
+/**
+ * Строки таблицы привязок компаньона.
+ *
+ * Компаньон правила держит три таблицы: чем вещи правила названы в этом дереве, где лежат
+ * механизмы и где исполняется каждая статья. Привязки — только третья, и берётся она по имени
+ * раздела, а не по месту в файле. Пока читался весь файл, строки первых двух попадали в список
+ * наравне с настоящими и тут же объявлялись расхождением: статьи с таким текстом в правиле нет
+ * и быть не может. Две трети перечня в дереве были ими, и правильно дописанная строка «Где это
+ * лежит» отвечала отказом.
+ *
+ * У компаньона спека домена раздела нет: там таблица одна, и сужать нечего — такой зовёт без
+ * имени раздела. У правила раздел стоит в образце компаньона, поэтому его отсутствие — отказ:
+ * молча прочесть вместо него весь файл значило бы вернуть тот же дефект.
+ */
+function rowsOfMap(specFile, mapFile, mapHeading) {
+    const text = read(mapFile);
+    if (!mapHeading) {
+        return text.split('\n');
+    }
+    const section = sectionOf(text, mapHeading);
+    if (!section.length) {
+        report(mapFile, `нет раздела \`${mapHeading}\` — привязкам правила негде лежать`);
+    }
+
+    return section;
+}
+
+function checkRuleImplementation(specFile, text, mapFile, heading = '## Правила', mapHeading = '') {
     const bullets = bulletsOf(sectionOf(text, heading));
     if (!bullets.length) {
         report(specFile, `в разделе \`${heading}\` нет ни одного пункта`);
@@ -244,7 +277,7 @@ function checkRuleImplementation(specFile, text, mapFile, heading = '## Прав
     }
 
     const rows = new Map();
-    for (const line of read(mapFile).split('\n')) {
+    for (const line of rowsOfMap(specFile, mapFile, mapHeading)) {
         const cells = line.match(/^\|([^|]+)\|([^|]*)\|\s*$/);
         if (!cells) {
             continue;
@@ -907,6 +940,8 @@ for (const file of walk(CONSTITUTION_DIR, (name) => name.endsWith('.md'))) {
 // Правило — скил с `kind: rule` в шапке. Оно и знает о проекте: имена, пути, связи. Привязка
 // его утверждений к коду живёт в `implementation.md` рядом со скилом.
 const RULE_HEADING = '## Как закон применяется здесь';
+/** Раздел компаньона правила, где лежат привязки; остальные его таблицы называют имена дерева. */
+const MAP_HEADING = '## Где исполняются статьи';
 
 /**
  * Шапка скила — первый блок между `---`. Читается только она: паттерн, который учит заводить
@@ -953,7 +988,7 @@ for (const file of walk('.claude/skills', (name) => name === 'SKILL.md')) {
     } else {
         ruled.add(law);
     }
-    checkRuleImplementation(file, text, `${dirname(file)}/implementation.md`, RULE_HEADING);
+    checkRuleImplementation(file, text, `${dirname(file)}/implementation.md`, RULE_HEADING, MAP_HEADING);
 
     const name = nameOf(head);
     if (name && name !== file.slice('.claude/skills/'.length, -'/SKILL.md'.length)) {

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

@@ -36,6 +36,18 @@ const DEFAULTS = {
     docsDir: 'docs',
     /** Отложенное: про него проверки молчат — оно описывает прошлое, а не дерево. */
     archiveDir: 'docs/archive/',
+    /**
+     * Каталоги, чей указатель сверяется с содержимым: обзорный документ в них перечисляет
+     * записи таблицей, и читатель ищет по ней, а не обходом. Пусто — сверки указателя нет.
+     */
+    indexedDirs: ['docs/archive/'],
+    /**
+     * Каталоги, где лежат исходники переносимых текстов. Такой текст называет адреса того
+     * дерева, куда он ложится, а не того, где написан, — и сверять его с этим деревом значит
+     * краснеть на каждый пример. Разложенную копию проверка узнаёт по шапке сама; сюда
+     * вносится только исходник. Пусто — переносимых текстов дерево не держит.
+     */
+    portableDirs: [],
     /** Где лежат спеки доменов; пусто — их в дереве нет, и сверка спеков не запускается. */
     specsDir: 'docs/specs',
     tasksDir: 'docs/tasks',

package/assets/commands/agent-kit-digest.md

@@ -0,0 +1,83 @@
+---
+description: Свести накопленные предложения и наблюдения в правки ресурсов пакета правил
+argument-hint: '[пусто | --days N]'
+---
+
+Собери предложения, пришедшие из деревьев, и скажи, что из них становится правкой пакета.
+Отрезок от пользователя: `$ARGUMENTS` (без довода — три дня).
+
+Зовётся **в репозитории самого пакета**, а не в дереве, где он стоит: здесь лежат ресурсы,
+которые предстоит править, и видно всех потребителей сразу. В чужом дереве команда бессмысленна
+— там есть только своя половина картины.
+
+## 1. Собери, что пришло
+
+```bash
+gh issue list --label agent-kit-feedback --state open --limit 100 \
+    --json number,title,body,createdAt
+```
+
+Помощник хостинга и учётная запись машинной работы у каждого дерева свои — как их звать здесь,
+сказано в компаньоне правила `git-workflow`.
+
+Каждая запись заведена командой `agent-kit propose` из дерева, где пакет стоит. В теле — ресурс,
+место, повод, готовый текст и сводка наблюдений того дерева. Имени дерева там нет намеренно:
+различать их можно только по сводке и по времени.
+
+Своё дерево тоже потребитель — его наблюдения читаются прямо:
+
+```bash
+npx agent-kit stats --days <отрезок> --json
+```
+
+## 2. Раздели повторившееся и разовое
+
+Это и есть работа сведения; всё остальное — оформление.
+
+- **Пришло об одном ресурсе из двух и более записей** — правка пакета. Разные деревья
+  споткнулись об одно и то же место, и чинить его надо там, откуда оно к ним приехало.
+- **Пришло однажды и называет то, чего у других нет** — надстройка того дерева, а не пакет.
+  Скажи это прямо и назови, куда именно: `overrides/<ресурс>` для текстов, карта гейта и
+  профиль — для родов файлов и команд.
+- **Пришло однажды, но верно любому дереву** — правка пакета. Числа записей мало: правило,
+  которое молчит о важном, молчит у всех, а споткнулся о него пока один.
+
+Ресурс, о котором пришли **противоречащие** предложения, в правку не идёт вовсе: неси оба
+владельцу. Слой правил, который говорит два разных, хуже слоя, который молчит.
+
+## 3. Посмотри, что говорят наблюдения
+
+Сводка отвечает на то, чего в предложениях нет:
+
+- **правило, разложенное и не загруженное ни разу** — кандидат на сокращение или на запись в
+  карте гейта: правило, которого гейт не требует, никто и не откроет;
+- **правило, которое гейт отбивает чаще прочих** — его либо забывают, либо оно требуется не
+  там; посмотри род правки в той же сводке;
+- **гард, отказывающий чаще прочих** — либо место поставки раз за разом делают не так, либо
+  отказ не называет, чем он снимается.
+
+## 4. Принеси правки
+
+По каждой — ресурс, место, готовый текст и число записей, из которых она вышла. Не правь ничего
+сам: решение принимает владелец, а работа идёт обычным ходом — задача, ветка, папка задачи.
+
+Заведи задачу на то, что владелец принял:
+
+```bash
+npm run task:new -- --title '<что не так>' --slug <короткое-имя> --label enhancement < тело.md
+```
+
+Записи, вошедшие в задачу, закрой ссылкой на неё:
+
+```bash
+gh issue close <номер> --comment 'Вошло в #<номер задачи>.'
+```
+
+## 5. Черновик записи в журнал изменений
+
+Собери его сразу, пока видно, из чего правка выросла: заголовок коммита по формату дерева и
+одна фраза о том, что менялось и почему. Журнал изменений при выпуске собирается из заголовков,
+и переписывать их задним числом — работа заново.
+
+**Выпуск отсюда не запускается.** Это отдельное решение владельца: слияние отчёта пакета не
+публикует. Скажи, что накопилось на выпуск, и остановись.