@rt-tools/agent-kit 0.10.0 → 0.12.0

package/assets/checks/check-file-size.mjs

@@ -35,8 +35,18 @@ import { join } from 'node:path';
 import { allowlistOf, baselineOf, CONFIG, ROOT, parseAllowlist } from './rt-kit-checks.config.mjs';
 
 const ALLOWLIST = allowlistOf('file-size');
-/** Предел один на все роды файлов: своё число каждому роду — спор о числе на каждой правке. */
+/** Пределов два: код и текст слоя правил. Какой из них применён, каждая строка отказа называет. */
 const LIMIT = CONFIG.fileSizeLimit;
+const PROSE_LIMIT = CONFIG.proseSizeLimit ?? CONFIG.fileSizeLimit;
+/** Корни текста слоя правил; дерево, их не назвавшее, судится одним пределом. */
+const PROSE_ROOTS = CONFIG.proseRoots ?? [];
+
+/** Предел для файла и имя предела для отказа: по корню, а не по расширению — код лежит и в `.md`. */
+function limitOf(path) {
+    return PROSE_ROOTS.some((root) => root && path.startsWith(root))
+        ? { limit: PROSE_LIMIT, title: 'предел текста' }
+        : { limit: LIMIT, title: 'предел кода' };
+}
 
 /** Роды файлов, которых не читает линтер. Код остаётся за ним. */
 const JUDGED = ['.md', '.scss', '.html', '.js', '.mjs', '.sh'];
@@ -78,7 +88,7 @@ const tracked = trackedFiles().filter(judged);
 
 for (const path of tracked) {
     const lines = lineCount(path);
-    if (lines > LIMIT) {
+    if (lines > limitOf(path).limit) {
         tooLong.set(path, lines);
     }
 }
@@ -95,7 +105,10 @@ const gone = [...known.keys()].filter((path) => !existsSync(join(ROOT, path)));
 const shrunk = [...known.keys()].filter((path) => !tooLong.has(path) && existsSync(join(ROOT, path)));
 
 const problems = [
-    ...fresh.map(([path, lines]) => `${path}: ${lines} строк, предел ${LIMIT} — делить, а не дописывать строку в ${ALLOWLIST}`),
+    ...fresh.map(([path, lines]) => {
+        const { limit, title } = limitOf(path);
+        return `${path}: ${lines} строк, ${title} ${limit} — делить, а не дописывать строку в ${ALLOWLIST}`;
+    }),
     ...gone.map((path) => `${path}: строка в ${ALLOWLIST} устарела — файла в дереве нет`),
     ...shrunk.map((path) => `${path}: значится в ${ALLOWLIST}, но уже короче предела — строку убрать`),
 ];
@@ -107,7 +120,9 @@ if (problems.length > 0) {
     process.exit(1);
 }
 
+const limits = PROSE_ROOTS.length > 0 ? `предел кода ${LIMIT}, предел текста ${PROSE_LIMIT}` : `предел ${LIMIT}`;
+
 console.log(
-    `check-file-size: проверено ${tracked.length} файлов, длиннее ${LIMIT} строк ${tooLong.size}, ` +
+    `check-file-size: проверено ${tracked.length} файлов, ${limits}, длиннее предела ${tooLong.size}, ` +
         `из них принято ${accepted.size}, долг ${debt.size} — новых нет`
 );

package/assets/checks/check-state-next.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * Сверка того, что раздел состояния называет следующее движение.
+ *
+ * Раздел, обрывающийся на последнем приёме, читается как конец работы: исполнитель
+ * доводит обязательное действие до конца, дочитывает раздел, следующего движения в
+ * нём не находит — и отдаёт ход отчётом о сделанном. Так кончились два хода: один
+ * на записанном замысле, второй на закрытом разборе просьбы. Сверка состояний этого
+ * не видит: она сравнивает имена разделов с перечнем и внутрь не смотрит.
+ *
+ * Читаются четыре текста:
+ *   перечень — таблица состояний в правиле ведения работы: имя и ведущий паттерн;
+ *   разделы  — заголовки вида «Состояние `имя`» в этих паттернах;
+ *   правило  — оно же: в нём стоит утверждение о границе состояния;
+ *   карта и закон — там же стоит то же утверждение, если дерево их разложило.
+ *
+ * Строка следующего движения узнаётся по зачину, а называет своё: единая дословная
+ * строка читается как шаблон и перестаёт замечаться на третьем разделе. Поэтому
+ * повтор хвоста считается расхождением наравне с его отсутствием.
+ *
+ * FAIL-OPEN: правила ведения работы в дереве нет — сверять нечего, нулевой код.
+ * Пустая таблица состояний отказом считается: она означает не «нечего сверять», а
+ * «перечень сломан». Ведущий паттерн, которого в дереве нет, здесь не судится — его
+ * называет сверка состояний, и два отказа об одном промахе читаются как две
+ * претензии.
+ *
+ * Ненулевой код возврата и перечень расхождений.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const RULE = join(ROOT, '.claude/skills/task-flow/SKILL.md');
+/**
+ * Правило хода захода: граница состояния живёт там, а не в правиле ведения работы.
+ * Разделились они, когда правило ведения работы вышло за предел длины: ход работы
+ * остался в одном, выходы хода уехали в другое. Дерево, где разложено только первое,
+ * судится по нему одному — второго файла у него нет.
+ */
+const TURN_RULE = join(ROOT, '.claude/skills/turn-conduct/SKILL.md');
+const SKILLS = join(ROOT, '.claude/skills');
+const MAP = join(ROOT, '.claude/rt-kit/defaults/turn-map.md');
+const LAW = join(ROOT, 'docs/constitution/work-conduct.md');
+
+/** Зачин строки: по нему её находят, а хвост у каждого раздела свой. */
+const MARKER = '**Следующее движение:**';
+
+/** Утверждение о границе состояния. Стоит в правиле, в карте и в законе теми же словами. */
+const BOUNDARY = 'Переход из состояния в состояние';
+
+/** Короче этого хвост движения не называет: зачин без движения — та же пустота. */
+const MIN_TAIL = 20;
+
+/** Имя состояния и паттерн, который его ведёт, — из таблицы правила. */
+function statesFromRule(text) {
+    const states = [];
+
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('|')) {
+            continue;
+        }
+
+        const cells = line
+            .split('|')
+            .slice(1, -1)
+            .map((cell) => cell.trim());
+
+        if (cells.length < 4) {
+            continue;
+        }
+
+        const name = cells[0].match(/^`([^`]+)`$/);
+        const pattern = cells[3].match(/^`([^`]+)`$/);
+
+        if (name && pattern) {
+            states.push({ name: name[1], pattern: pattern[1] });
+        }
+    }
+
+    return states;
+}
+
+/** Разделы состояний паттерна: имя, заголовок целиком и найденные в разделе строки движения. */
+function sectionsOf(pattern) {
+    const file = join(SKILLS, pattern, 'SKILL.md');
+
+    if (!existsSync(file)) {
+        return null;
+    }
+
+    const sections = [];
+    let current = null;
+
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        const heading = line.match(/^#+\s+Состояние\s+`([^`]+)`/);
+
+        if (heading) {
+            current = { name: heading[1], heading: line.replace(/^#+\s+/, ''), moves: [] };
+            sections.push(current);
+            continue;
+        }
+
+        if (current && line.startsWith(MARKER)) {
+            current.moves.push(line.slice(MARKER.length).trim());
+        }
+    }
+
+    return sections;
+}
+
+if (!existsSync(RULE)) {
+    console.log('check-state-next: правила ведения работы в дереве нет — сверять нечего');
+    process.exit(0);
+}
+
+const ruleText = readFileSync(RULE, 'utf8');
+const states = statesFromRule(ruleText);
+
+if (states.length === 0) {
+    console.error('check-state-next: в правиле ведения работы не нашлось таблицы состояний');
+    process.exit(1);
+}
+
+const problems = [];
+const patterns = new Map();
+const tails = new Map();
+let counted = 0;
+
+for (const state of states) {
+    if (!patterns.has(state.pattern)) {
+        patterns.set(state.pattern, sectionsOf(state.pattern));
+    }
+}
+
+for (const [pattern, sections] of patterns) {
+    if (sections === null) {
+        continue;
+    }
+
+    for (const section of sections) {
+        counted += 1;
+
+        const where = `\`${section.name}\` в паттерне \`${pattern}\``;
+
+        if (section.moves.length === 0) {
+            problems.push(`${where}: в разделе «${section.heading}» нет строки «${MARKER}»`);
+            continue;
+        }
+
+        if (section.moves.length > 1) {
+            problems.push(`${where}: в разделе «${section.heading}» таких строк ${section.moves.length}, а движение одно`);
+            continue;
+        }
+
+        const tail = section.moves[0];
+
+        if (tail.length < MIN_TAIL) {
+            problems.push(`${where}: зачин есть, а движение за ним не названо`);
+            continue;
+        }
+
+        const twin = tails.get(tail);
+
+        if (twin) {
+            problems.push(`${where}: движение слово в слово то же, что у ${twin}`);
+            continue;
+        }
+
+        tails.set(tail, `\`${section.name}\` в паттерне \`${pattern}\``);
+    }
+}
+
+if (counted === 0) {
+    problems.push('ни одного раздела состояния не нашлось: паттерны не разложены или заголовки в них другие');
+}
+
+const turnText = existsSync(TURN_RULE) ? readFileSync(TURN_RULE, 'utf8') : '';
+if (!ruleText.includes(BOUNDARY) && !turnText.includes(BOUNDARY)) {
+    problems.push(`правило хода захода о границе состояния молчит: строки «${BOUNDARY}» в нём нет`);
+}
+
+for (const [file, what] of [
+    [MAP, 'карта хода'],
+    [LAW, 'закон о ведении работы'],
+]) {
+    if (existsSync(file) && !readFileSync(file, 'utf8').includes(BOUNDARY)) {
+        problems.push(`${what} о границе состояния молчит: строки «${BOUNDARY}» в ней нет`);
+    }
+}
+
+if (problems.length > 0) {
+    console.error(`check-state-next: расхождений ${problems.length}`);
+
+    for (const problem of problems) {
+        console.error(`  ${problem}`);
+    }
+
+    console.error('\nСтрока следующего движения стоит в каждом разделе состояния: зачин общий, движение своё.');
+    process.exit(1);
+}
+
+console.log(`check-state-next: разделов состояния ${counted}, у каждого названо следующее движение`);

package/assets/checks/check-states.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * Сверка перечня состояний работы с разделами паттернов, которые их ведут.
+ *
+ * Состояние без ведущего текста читается как конец работы: исполнитель дочитывает
+ * паттерн до последнего раздела, следующего движения в нём нет, и ход кончается
+ * отчётом. Так простояло состояние «замысел записан» — оно встречалось один раз,
+ * клеткой таблицы, и дыру нашло происшествие, а не проверка. Разбор —
+ * `docs/postmortems/2026-08-21-turn-ended-at-the-written-plan.md`.
+ *
+ * Сверяются два множества в обе стороны:
+ *   перечень — таблица состояний в правиле ведения работы: имя и ведущий паттерн;
+ *   разделы  — заголовки вида «Состояние `имя`» в паттернах.
+ *
+ * Состояние без раздела — расхождение. Раздел про состояние вне перечня — тоже:
+ * переименованное состояние иначе оставляет прежний раздел, и тот выглядит
+ * действующим.
+ *
+ * Ведущий паттерн берётся из самой таблицы, а не из имён файлов: раздел, лежащий
+ * не в том паттерне, который назначен, читателя до себя не доводит — он открывает
+ * назначенный.
+ *
+ * FAIL-OPEN: правила ведения работы в дереве нет — сверять нечего, нулевой код.
+ * Пустая таблица состояний отказом считается: она означает не «нечего сверять», а
+ * «перечень сломан».
+ *
+ * Ненулевой код возврата и перечень расхождений.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const RULE = join(ROOT, '.claude/skills/task-flow/SKILL.md');
+const SKILLS = join(ROOT, '.claude/skills');
+
+/** Имя состояния и паттерн, который его ведёт, — из таблицы правила. */
+function statesFromRule(text) {
+    const states = [];
+
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('|')) {
+            continue;
+        }
+
+        const cells = line
+            .split('|')
+            .slice(1, -1)
+            .map((cell) => cell.trim());
+
+        if (cells.length < 4) {
+            continue;
+        }
+
+        const name = cells[0].match(/^`([^`]+)`$/);
+        const pattern = cells[3].match(/^`([^`]+)`$/);
+
+        if (name && pattern) {
+            states.push({ name: name[1], pattern: pattern[1] });
+        }
+    }
+
+    return states;
+}
+
+/** Состояния, про которые в паттерне есть раздел. Заголовок любого уровня. */
+function sectionsOf(pattern) {
+    const file = join(SKILLS, pattern, 'SKILL.md');
+
+    if (!existsSync(file)) {
+        return null;
+    }
+
+    const found = new Set();
+
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+        const heading = line.match(/^#+\s+Состояние\s+`([^`]+)`/);
+
+        if (heading) {
+            found.add(heading[1]);
+        }
+    }
+
+    return found;
+}
+
+if (!existsSync(RULE)) {
+    console.log('check-states: правила ведения работы в дереве нет — сверять нечего');
+    process.exit(0);
+}
+
+const states = statesFromRule(readFileSync(RULE, 'utf8'));
+
+if (states.length === 0) {
+    console.error('check-states: в правиле ведения работы не нашлось таблицы состояний');
+    process.exit(1);
+}
+
+const known = new Set(states.map((state) => state.name));
+const problems = [];
+const seen = new Map();
+
+for (const state of states) {
+    if (!seen.has(state.pattern)) {
+        seen.set(state.pattern, sectionsOf(state.pattern));
+    }
+
+    const sections = seen.get(state.pattern);
+
+    if (sections === null) {
+        problems.push(`состояние \`${state.name}\`: ведущий паттерн \`${state.pattern}\` в дереве не разложен`);
+        continue;
+    }
+
+    if (!sections.has(state.name)) {
+        problems.push(`состояние \`${state.name}\`: в паттерне \`${state.pattern}\` нет раздела «Состояние \`${state.name}\`»`);
+    }
+}
+
+for (const [pattern, sections] of seen) {
+    if (sections === null) {
+        continue;
+    }
+
+    for (const name of sections) {
+        if (!known.has(name)) {
+            problems.push(`паттерн \`${pattern}\`: раздел про \`${name}\`, а такого состояния в перечне нет`);
+        }
+    }
+}
+
+if (problems.length > 0) {
+    console.error(`check-states: расхождений ${problems.length}`);
+
+    for (const problem of problems) {
+        console.error(`  ${problem}`);
+    }
+
+    console.error('\nПеречень состояний — правило `task-flow`, разделы — паттерны при нём.');
+    process.exit(1);
+}
+
+console.log(`check-states: состояний ${states.length}, у каждого есть раздел в ведущем паттерне`);

package/assets/checks/check-turn-map.mjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Сверка карты хода: её размер и её полнота.
+ *
+ * Карту кладёт в контекст хук входа в заход — целиком, до первой реплики. Тем она и
+ * отличается от правила: правило исполнитель читает сам и платит за это ходом, карта
+ * приходит даром. Даром — пока она короткая: карта, выросшая до правила, съедает то
+ * самое окно, ради которого её и заводили, и заметить это нечем — она продолжает
+ * приходить и продолжает быть верной.
+ *
+ * Второе, чего не видно без сверки: состояние, заведённое в правиле и забытое в карте.
+ * Заход тогда получает карту, не находит в ней своего состояния и идёт читать правило —
+ * то есть карта работает ровно до первого нового состояния.
+ *
+ * Сверяются три вещи:
+ *   размер    — байты разложенной карты против объявленного предела;
+ *   состояния — имена из таблицы правила против имён в карте, в обе стороны;
+ *   выходы    — все четыре выхода хода названы.
+ *
+ * FAIL-OPEN: карты в дереве нет — сверять нечего, нулевой код. Дерево может её не
+ * раскладывать. Пустая таблица состояний в карте отказом считается: это не «нечего
+ * сверять», а «карта сломана».
+ *
+ * Ненулевой код возврата и перечень расхождений.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ROOT = process.cwd();
+const MAP = join(ROOT, '.claude/rt-kit/defaults/turn-map.md');
+const RULE = join(ROOT, '.claude/skills/task-flow/SKILL.md');
+
+/**
+ * Предел размера карты в байтах.
+ *
+ * Число одно и живёт здесь: карта приходит в каждый заход целиком, и предел ей — свойство
+ * приёма, а не дерева. Шесть килобайт взяты замером, а не на глаз: карта в день заведения
+ * весит 4495 байт, правило, из которого она выжата, — 63803. Запас в полтора килобайта —
+ * это два-три новых состояния; выйдя за него, карта перестаёт быть выжимкой, и делить её
+ * тогда надо, а не поднимать предел.
+ */
+const LIMIT_BYTES = 6144;
+
+/** Имена состояний из таблицы: первая ячейка в обратных кавычках и всё, что за ней. */
+function statesOf(text) {
+    const states = [];
+
+    for (const line of text.split('\n')) {
+        if (!line.startsWith('|')) {
+            continue;
+        }
+
+        const cells = line
+            .split('|')
+            .slice(1, -1)
+            .map((cell) => cell.trim());
+
+        if (cells.length < 2) {
+            continue;
+        }
+
+        const name = cells[0].match(/^`([^`]+)`$/);
+
+        if (name) {
+            states.push({ name: name[1], rest: cells.slice(1) });
+        }
+    }
+
+    return states;
+}
+
+/** Выходы хода, названные законом. Ищутся по началу строки таблицы, а не по всему тексту. */
+const EXITS = ['вопрос владельцу', 'отказ гарда', 'заполненное окно', 'работа отдана'];
+
+function main() {
+    if (!existsSync(MAP)) {
+        console.log('check-turn-map: карты хода в дереве нет — сверять нечего');
+
+        return 0;
+    }
+
+    const text = readFileSync(MAP, 'utf8');
+    const bytes = statSync(MAP).size;
+    const faults = [];
+
+    if (bytes > LIMIT_BYTES) {
+        faults.push(`карта выросла: ${bytes} байт при пределе ${LIMIT_BYTES}`);
+    }
+
+    const inMap = statesOf(text);
+
+    if (inMap.length === 0) {
+        faults.push('в карте нет ни одного состояния — таблица сломана');
+    }
+
+    for (const state of inMap) {
+        if (!state.rest[0]) {
+            faults.push(`${state.name}: в карте нет обязательного действия`);
+        }
+    }
+
+    if (existsSync(RULE)) {
+        const inRule = statesOf(readFileSync(RULE, 'utf8'));
+        const mapNames = new Set(inMap.map((state) => state.name));
+        const ruleNames = new Set(inRule.map((state) => state.name));
+
+        for (const state of ruleNames) {
+            if (!mapNames.has(state)) {
+                faults.push(`${state}: состояние объявлено правилом и забыто в карте`);
+            }
+        }
+
+        for (const state of mapNames) {
+            if (!ruleNames.has(state)) {
+                faults.push(`${state}: состояние стоит в карте, а правило его не объявляет`);
+            }
+        }
+    }
+
+    for (const exit of EXITS) {
+        if (!text.includes(exit)) {
+            faults.push(`выход хода «${exit}» в карте не назван`);
+        }
+    }
+
+    if (faults.length > 0) {
+        console.log(`check-turn-map: расхождений ${faults.length}, размер ${bytes} байт при пределе ${LIMIT_BYTES}\n`);
+
+        for (const fault of faults) {
+            console.log(`  ${fault}`);
+        }
+
+        console.log('\nКарта короче правила — этим она и полезна. Выросшая, она съедает то окно, ради');
+        console.log('которого её кладут в контекст. Правится она в ресурсе пакета, а не в разложенной копии.');
+
+        return 1;
+    }
+
+    console.log(
+        `check-turn-map: ${inMap.length} состояний, ${EXITS.length} выхода хода, ` + `${bytes} байт при пределе ${LIMIT_BYTES} — сошлось`
+    );
+
+    return 0;
+}
+
+process.exit(main());

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

@@ -67,10 +67,24 @@ const DEFAULTS = {
      */
     generatedDirs: [],
     /**
-     * Предел длины файла — одно число на все роды: своё число каждому роду означает спор о
-     * числе на каждой правке, а не о длине файла.
+     * Предел длины файла для кода и обвязки. Родов у него по-прежнему не два десятка, а два:
+     * код и текст слоя правил. Спорить о числе на каждой правке нечему — оба числа стоят
+     * здесь и меняются работой, а не по ходу.
      */
     fileSizeLimit: 500,
+    /**
+     * Предел длины текста слоя правил — закона, правила, паттерна, холодной части и их
+     * источников. Он ниже предела кода вдвое, и это не строгость ради строгости: текст, не
+     * влезающий на экран целиком, дописывают в конец, не перечитав начала, — так в одном файле
+     * и оказываются два ответа на один вопрос. У кода от этого спасает линтер, у текста —
+     * только это число.
+     */
+    proseSizeLimit: 300,
+    /**
+     * Корни, под которыми лежит текст слоя правил, и его источники. Файл отсюда судится
+     * пределом текста, всё остальное — пределом кода. Пусто — предел один на всё дерево.
+     */
+    proseRoots: [],
     /**
      * Внешние пакеты, чьи перечисления считаются наравне с либами: своё перечисление под уже
      * объявленный там набор — такая же копия, как и между двумя либами. Каждая запись — имя