@rt-tools/agent-kit 0.4.0 → 0.5.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;
@@ -730,6 +763,20 @@ function collectReferences() {
             // идентификатором: состояние теста читается, когда файл разобран целиком
             found.forEach(({ id, test: own, place }) => remember(id, { place, screen: Boolean(e2eRoot), off: Boolean(own?.off) }));
         }
+
+        // Наборы сценариев на shell. Так проверяются исполняемые файлы — гарды, проверки,
+        // умолчания: они не на TypeScript, и набор к ним пишут на том же языке, что и их
+        // самих. Выключателей здесь нет: пропустить сценарий в таком наборе нечем, поэтому
+        // достаточно найти идентификатор.
+        for (const file of walk(root, (name) => name.endsWith('.test.sh'))) {
+            read(file)
+                .split('\n')
+                .forEach((line, index) => {
+                    for (const [id] of line.matchAll(SCENARIO_REFERENCE)) {
+                        remember(id, { place: `${file}:${index + 1}`, screen: false, off: false });
+                    }
+                });
+        }
     }
 
     return references;
@@ -774,15 +821,47 @@ for (const file of walk(CONSTITUTION_DIR, (name) => name.endsWith('.md'))) {
     laws.set(name, file);
 }
 
+/**
+ * Директории, описывающие предмет: сам домен и его поддомены. Поддомен заводится, когда домен
+ * вырос настолько, что читать его целиком ради одной подробности дороже, чем найти её; устроен
+ * он так же — три файла и свой префикс сценариев.
+ *
+ * `proposed/` предметом не является: это договорённость о продукте до кода, и её сценарии живут
+ * в нумерации того спека, в который она вольётся.
+ */
+function collectSpecDirs(base) {
+    const found = [base];
+    let entries;
+    try {
+        entries = readdirSync(join(ROOT, base), { withFileTypes: true });
+    } catch {
+        return found;
+    }
+
+    for (const entry of entries) {
+        if (entry.isDirectory() && entry.name !== 'proposed') {
+            found.push(...collectSpecDirs(`${base}/${entry.name}`));
+        }
+    }
+
+    return found;
+}
+
+/** Префикс сценариев принадлежит одному спеку по всему дереву. */
+const prefixOwners = new Map();
+
 for (const domain of domains) {
     const base = `${SPECS_DIR}/${domain}`;
-    // Домен, у которого есть только `proposed/`, ещё не существует: спека о нём
-    // нет, пока фича не выкачена
-    const isProposedOnly = exists(`${base}/proposed`) && !exists(`${base}/spec.md`);
-    if (!isProposedOnly) {
+    for (const dir of collectSpecDirs(base)) {
+        // Спек, у которого есть только `proposed/`, ещё не существует: его самого нет, пока
+        // фича не выкачена
+        if (exists(`${dir}/proposed`) && !exists(`${dir}/spec.md`)) {
+            continue;
+        }
+        const what = dir === base ? 'домен' : 'поддомен';
         ['spec.md', 'scenarios.md']
-            .filter((name) => !exists(`${base}/${name}`))
-            .forEach((name) => report(base, `нет файла \`${name}\` — домен описан наполовину`));
+            .filter((name) => !exists(`${dir}/${name}`))
+            .forEach((name) => report(dir, `нет файла \`${name}\` — ${what} описан наполовину`));
     }
 
     // Спеки фич из `proposed/` проверяются наравне со спеком домена: они и есть
@@ -803,10 +882,38 @@ for (const domain of domains) {
     }
 
     const found = walk(base, (name) => name === 'scenarios.md').flatMap(parseScenarios);
-    const prefixes = new Set(found.map((scenario) => scenario.prefix));
-    if (prefixes.size > 1) {
-        report(base, `в домене больше одного префикса сценариев: ${[...prefixes].sort().join(', ')}`);
+
+    // Префикс судится в пределах одного спека, а не всего дерева домена: у поддомена он свой, и
+    // по номеру видно, о чём сценарий. Два префикса в одном спеке по-прежнему означают, что
+    // предмет описан дважды.
+    const prefixesOf = new Map();
+    for (const scenario of found) {
+        const dir = dirname(scenario.file);
+        if (!prefixesOf.has(dir)) {
+            prefixesOf.set(dir, new Set());
+        }
+        prefixesOf.get(dir).add(scenario.prefix);
+    }
+
+    for (const [dir, prefixes] of prefixesOf) {
+        if (prefixes.size > 1) {
+            report(dir, `в спеке больше одного префикса сценариев: ${[...prefixes].sort().join(', ')}`);
+        }
+        // Договорённость о продукте нумеруется вместе со спеком, в который вольётся:
+        // идентификаторы переезд переживают, и занятым префикс от неё не становится
+        if (dir.includes('/proposed/')) {
+            continue;
+        }
+        for (const prefix of prefixes) {
+            const owner = prefixOwners.get(prefix);
+            if (owner && owner !== dir) {
+                report(dir, `префикс \`SC-${prefix}\` уже занят — \`${owner}\`; по номеру не видно, чей сценарий`);
+                continue;
+            }
+            prefixOwners.set(prefix, dir);
+        }
     }
+
     scenarios.push(...found);
 }
 
@@ -833,6 +940,8 @@ for (const file of walk(CONSTITUTION_DIR, (name) => name.endsWith('.md'))) {
 // Правило — скил с `kind: rule` в шапке. Оно и знает о проекте: имена, пути, связи. Привязка
 // его утверждений к коду живёт в `implementation.md` рядом со скилом.
 const RULE_HEADING = '## Как закон применяется здесь';
+/** Раздел компаньона правила, где лежат привязки; остальные его таблицы называют имена дерева. */
+const MAP_HEADING = '## Где исполняются статьи';
 
 /**
  * Шапка скила — первый блок между `---`. Читается только она: паттерн, который учит заводить
@@ -879,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)) {
@@ -887,11 +996,16 @@ for (const file of walk('.claude/skills', (name) => name === 'SKILL.md')) {
     }
 }
 
+// Предложенный закон правила не требует: договорённость записана раньше кода, привязывать её
+// не к чему, и требование правила заставило бы завести его с якорями в несуществующие места.
+// Признак стоит строкой статуса в самом законе, а не списком исключений рядом с проверкой.
+const isProposedLaw = (file) => /^\*\*Статус:\*\*\s*предложен/m.test(read(file));
+
 // Обратные стороны связи. Закон без правила читается как договорённость, которую этот проект
 // не применяет; правило без паттерна оставляет готовый код там, где ему не место, — в самом
 // правиле, которое читается при каждой правке.
 [...laws]
-    .filter(([law]) => !ruled.has(law))
+    .filter(([law, file]) => !ruled.has(law) && !isProposedLaw(file))
     .forEach(([, file]) => report(file, 'у закона нет ни одного правила — заведи скил с `law:` на него'));
 
 for (const file of walk('.claude/skills', (name) => name === 'SKILL.md')) {

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/next-session.md

@@ -0,0 +1,122 @@
+---
+description: Закрытие захода — главная ветка подтянута, влитые ветки сняты, передача написана
+argument-hint: '[пусто | <что дописать в передачу от себя>]'
+---
+
+Закрой заход: приведи дерево к главной ветке, убери влитые ветки и напиши передачу для
+следующего захода. Дописка владельца к передаче: `$ARGUMENTS`
+
+Вызывается **последним действием захода** — после того, как работа закоммичена, а отчёт открыт
+или влит. Команда ничего не мержит, не пушит и не открывает: закрытие захода — уборка, а не
+поставка.
+
+## 1. Прочитай профиль дерева
+
+Имя главной ветки, каталог папок задач и каталог передачи у каждого дерева свои:
+
+```bash
+for profile in .claude/rt-kit/defaults/project.sh .claude/rt-kit/project.sh; do
+    [ -f "$profile" ] && . "$profile"
+done
+printf 'главная: %s · задачи: %s · передача: %s\n' \
+    "${RT_MAIN_BRANCH:-main}" "${RT_TASKS_DIR:-docs/tasks}" "${RT_HANDOFF_DIR:-.claude/handoff}"
+```
+
+Зашивать эти имена в команду нельзя: в первом же дереве, которое зовёт главную ветку иначе,
+уборка уедет не туда.
+
+## 2. Остановись, если в дереве есть незакоммиченное
+
+```bash
+git status --short
+```
+
+Непустой вывод — конец команды. Назови файлы владельцу и не трогай ни веток, ни главной: смена
+ветки уносит правку за собой или отбивается на полпути, а решает, что с ней делать, владелец.
+
+Неотслеживаемый файл — тоже незакоммиченное. Скажи о нём отдельной строкой: он мог остаться от
+работы, которую бросили.
+
+## 3. Пойми, по правилу ли ведётся работа
+
+```bash
+git fetch --prune --quiet
+branch="$(git branch --show-current)"
+```
+
+Работа идёт **по правилу**, если имя ветки несёт номер задачи — это `rt_task_branch_ok` из
+профиля — или если в каталоге папок задач лежит папка с именем ветки. Отчёт **влит**, когда
+коммиты ветки уже есть в удалённой главной:
+
+```bash
+git merge-base --is-ancestor HEAD "origin/${RT_MAIN_BRANCH:-main}" && echo влит || echo 'не влит'
+```
+
+## 4. Приведи дерево к главной ветке
+
+- **Работа по правилу и отчёт влит** — задача закрыта, ветка больше не нужна:
+
+    ```bash
+    git switch "${RT_MAIN_BRANCH:-main}" && git pull --ff-only
+    ```
+
+- **Всё остальное** — работа не кончилась, и ветка остаётся местом, где она продолжится:
+
+    ```bash
+    git merge "origin/${RT_MAIN_BRANCH:-main}"
+    ```
+
+    Конфликт разбирается сейчас, а не в начале следующего захода: назови его владельцу и
+    останови команду до его решения.
+
+## 5. Убери ветки
+
+Снимаются только влитые в главную: их коммиты есть в ней, и восстанавливать нечего.
+
+```bash
+git branch --merged "${RT_MAIN_BRANCH:-main}" \
+    | grep -vE "^\*|^\s*${RT_MAIN_BRANCH:-main}$" \
+    | xargs -r git branch -d
+```
+
+Невлитую ветку **не сноси**. Назови её владельцу вместе с числом коммитов, которых нет в
+главной, — по ним видно, что именно потеряется, если её снести:
+
+```bash
+for b in $(git branch --no-merged "${RT_MAIN_BRANCH:-main}" --format='%(refname:short)'); do
+    printf '%s: %s коммитов мимо главной\n' "$b" "$(git rev-list --count "${RT_MAIN_BRANCH:-main}..$b")"
+done
+```
+
+Мёртвые ссылки на удалённые ветки снял `git fetch --prune` шагом 3.
+
+## 6. Напиши передачу
+
+Что в ней стоит и в какой форме — паттерн `task-flow-handoff`; здесь только место и порядок.
+Файл один на ветку и лежит вне истории дерева:
+
+```bash
+mkdir -p "${RT_HANDOFF_DIR:-.claude/handoff}"
+# файл — ${RT_HANDOFF_DIR:-.claude/handoff}/<ветка>.md
+```
+
+Имя берётся от той ветки, в которой шла работа, — не от той, куда команда перешла шагом 4.
+
+К тому, что требует паттерн, эта команда добавляет своё: что она убрала — снятые ветки,
+состояние главной, оставшееся невлитым. Следующий заход начинается ровно с этого.
+
+Заход, кончившийся ничем, передачу пишет тоже: «пробовали так — не вышло, потому что» стоит
+дороже пустого файла. Дописку владельца из `$ARGUMENTS` вставь своим разделом, не пересказывая.
+
+## 7. Отдай итог
+
+Последней строкой — путь к передаче: владелец вставляет её в новый заход одной вставкой. Перед
+ней: что стало с главной веткой, какие ветки сняты, какие остались невлитыми. Содержание
+передачи не пересказывай — владелец её и так прочитает.
+
+## Чего команда не делает
+
+- не мержит отчёт и не пушит: это поставка, и вслепую она не делается;
+- не сносит невлитую ветку и не трогает папку задачи;
+- не коммитит передачу — она лежит вне дерева намеренно, иначе рядом с ходом работы заводится
+  вторая запись об одном и том же.

package/assets/defaults/gate-map.sh

@@ -51,7 +51,15 @@ skill_for_default() {
     case "$kind" in
         edit)
             case "$target" in
-                # Файлы самого агента правятся без правила: правило на них — это оно само.
+                # Правило и паттерн — такая же договорённость, как спек: обязательные разделы,
+                # утверждение с привязкой, граница между статьёй закона и утверждением правила.
+                # Ветка стоит раньше общего исключения и раньше `*.md`: под исключением текст
+                # правила переписывался без единого требования, а `*.md` увёл бы его в правило
+                # формулировок — оно про слова, не про устройство.
+                */.claude/skills/*.md) printf '%s\n' 'spec-driven' ;;
+
+                # Остальные файлы самого агента правятся без правила: правило на них — это оно
+                # само.
                 */.claude/skills/* | */.claude/agents/* | */.claude/commands/* | */.claude/workflows/*) return 0 ;;
 
                 # Тексты проекта. Спек держит устройство домена, закон — договорённость,
@@ -61,8 +69,26 @@ skill_for_default() {
                 */docs/constitution/*) printf '%s\n' 'spec-driven' ;;
                 *.md) printf '%s\n' 'doc-style' ;;
 
-                # Поставка: состав зависимостей — это то, что приезжает на прод.
-                */package.json | */pnpm-lock.yaml | */pnpm-workspace.yaml | */package-lock.json) printf '%s\n' 'dependencies' ;;
+                # Конфиги линтеров — то же самое, только запреты в них исполняемые: они и есть
+                # исполнение правил про типы и про оформление, а комментарии в них пересказывают
+                # эти правила поимённо. Правились без единого правила под рукой.
+                */eslint.config.mjs | */eslint.config.js) printf '%s\n' 'typescript-conventions' ;;
+                */stylelint.config.js | */stylelint.config.mjs) printf '%s\n' 'styling-bem' ;;
+
+                # Проверка повторов исполняет утверждения правила об общем коде и требуется
+                # только им: правило о раскладке либ говорит про неё одной строкой с отсылкой,
+                # а привязки её признаков стоят при общем коде. Два отказа подряд на правку двух
+                # строк комментария стоят захода, а второе прочитанное правило не пригождается.
+                */tools/check-dupes.mjs | */tools/dupes-allowlist.json) printf '%s\n' 'shared-code' ;;
+
+                # Поставка: состав зависимостей — это то, что приезжает на прод. Правка
+                # скриптов зависимостью не является, и правило про версии на неё не вступает.
+                # Оговорка: удаление зависимости приходит правкой без номера версии и сюда не
+                # попадает — его ловит снимок дерева, который правится тем же коммитом.
+                */package.json)
+                    printf '%s' "$written" | grep -qE '"(dependencies|devDependencies|peerDependencies|optionalDependencies|overrides|resolutions|packageManager)"|"[^"]+"[[:space:]]*:[[:space:]]*"[~^]?[0-9]+\.[0-9]+' \
+                        && printf '%s\n' 'dependencies' ;;
+                */pnpm-lock.yaml | */pnpm-workspace.yaml | */package-lock.json) printf '%s\n' 'dependencies' ;;
 
                 # Границы между либами: манифест, алиасы, барель.
                 */project.json | */tsconfig.base.json | */eslint/boundaries/* | */src/index.ts | */public-api.ts | */ng-package.json)

package/assets/defaults/project.sh

@@ -72,6 +72,54 @@ rt_lint_for_default() {
 # Каталог папок задач. Пусто — ведения работы папкой в дереве нет, и гард замысла молчит.
 RT_TASKS_DIR="${RT_TASKS_DIR:-docs/tasks}"
 
+# Каталог записей о законченных работах. Туда переносят то, что объясняет решения закрытой
+# задачи. Гард поставки требует, чтобы ветка, удалившая папку задачи, что-то сюда добавила:
+# удалить проще, чем разобрать, а слова владельца больше нигде не записаны.
+RT_ARCHIVE_DIR="${RT_ARCHIVE_DIR:-docs/archive}"
+
+# Размер окна захода в токенах и пороги стража. Пусто — стража нет: считать долю не от чего, а
+# выведенный из записи захода размер врал бы — модель записана там без пометки о расширенном
+# окне. Дерево задаёт его в настройке агента, переменной окружения того же имени.
+RT_WINDOW_TOKENS="${RT_WINDOW_TOKENS:-}"
+RT_WINDOW_WARN_PCT="${RT_WINDOW_WARN_PCT:-40}"
+RT_WINDOW_STOP_PCT="${RT_WINDOW_STOP_PCT:-50}"
+
+# Куда кладётся передача захода. Вне дерева: состояние работы живёт в ходе работы и коммитится,
+# а передача его пересказывает для вставки в новый заход и в историю не едет.
+RT_HANDOFF_DIR="${RT_HANDOFF_DIR:-.claude/handoff}"
+
+# Команды, которые проходят после порога остановки: ими заход закрывается. Отбить их значило бы
+# отобрать у него единственный способ закончиться. Вызов считается по началу строки или сразу за
+# разделителем — упоминание команды в тексте командой не является.
+rt_handoff_allowed_cmd_default() {
+    case "$1" in
+        git\ * | *[\;\&\|]\ *git\ * | *\$\(git\ *) return 0 ;;
+        gh\ * | */gh\ * | glab\ * | */glab\ * | az\ * | */az\ *) return 0 ;;
+        *task:move* | *check:* | mkdir\ -p\ * | cat\ * | ls\ *) return 0 ;;
+    esac
+
+    return 1
+}
+
+# Где лежат тексты, которые читают до вопроса владельцу: законы, правила и договорённости о
+# продукте. По ним гард разговора судит, читалось ли за ход хоть что-то, и их же называет в
+# подсказке. Пусто у законов и правил разом — дерево этого требования не получает: читать
+# нечего.
+RT_LAWS_DIR="${RT_LAWS_DIR:-docs/constitution}"
+RT_RULES_DIR="${RT_RULES_DIR:-.claude/skills}"
+RT_SPECS_DIR="${RT_SPECS_DIR:-docs/specs}"
+
+# Главная ветка. Гарду она нужна, чтобы найти общего предка и понять, что ветка сделала с
+# папкой задачи и с архивом. Если общего предка нет, сравнивать не с чем — проверка молчит.
+RT_MAIN_BRANCH="${RT_MAIN_BRANCH:-main}"
+
+# Тело PR по его номеру. Обход требования пишут в PR, а в команде слияния его нет — там только
+# номер. Пустой ответ значит «спросить не у кого»: тогда обход ищется только в тексте команды.
+rt_report_body_default() {
+    command -v gh >/dev/null 2>&1 || return 1
+    gh pr view "$1" --json body -q '.body' 2>/dev/null
+}
+
 # Код приложения ли это. Успех — да, и тогда правка требует замысла на диске.
 #
 # Признак — путь, а не оценка на глаз: оценку назначает тот, кому она мешает, и порог плывёт.
@@ -177,3 +225,5 @@ rt_reinvented_in() { rt_reinvented_in_default "$@"; }
 rt_is_app_code() { rt_is_app_code_default "$@"; }
 rt_qa_decorative() { rt_qa_decorative_default "$@"; }
 rt_task_state() { rt_task_state_default "$@"; }
+rt_report_body() { rt_report_body_default "$@"; }
+rt_handoff_allowed_cmd() { rt_handoff_allowed_cmd_default "$@"; }

package/assets/docs/GLOSSARY.md

@@ -0,0 +1,74 @@
+# Словарь проекта
+
+Слова, которые в этом дереве значат что-то определённое. Читается перед тем, как написать спек,
+правило, комментарий, тело коммита или описание отчёта: слово отсюда употребляется в том
+значении, что здесь, а слово не отсюда либо заводится здесь же, либо заменяется простым.
+
+Термины одного домена живут в разделе «Терминология» его спека — здесь только те, что проходят
+сквозь весь проект.
+
+Разделы ниже везёт пакет: это слова слоя правил, и значат они одно и то же везде, где он стоит.
+Предметные слова дерево дописывает своими разделами через надстройку — они сливаются сюда по
+заголовкам, и правка пакета их не трогает.
+
+## Слой правил
+
+| Термин                    | Что это                                                                                                                                                     |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Закон                     | Файл в каталоге конституции. Говорит, что должно быть верно, и не знает ни путей, ни имён файлов. Верен для любого приложения этого класса                  |
+| Законы приложения         | Слой законов, верных только для этого приложения: деньги, локали, доступ. Предметность в них законна — она их предмет                                       |
+| Правило                   | Скил с `kind: rule`. Привязывает закон к этому дереву: чем это здесь названо и где лежит                                                                    |
+| Паттерн                   | Скил с `kind: pattern`. Готовый код и порядок действий; стоит при правиле                                                                                   |
+| Компаньон                 | Файл `implementation.md` рядом с правилом: имена и пути этого дерева. Пакет знает приём, но не знает имён — их пишет проект                                 |
+| Спек                      | Описание домена: как он работает. Говорит об установившемся, а не о предстоящем                                                                             |
+| Домен                     | Предмет, у которого свой спек. Выросший домен делится на поддомены, а не на соседние домены                                                                 |
+| Сценарий                  | Наблюдаемое поведение под номером `SC-<ПРЕФИКС>-<НОМЕР>`. Номер стоит в заголовке теста                                                                     |
+| Привязка                  | Строка `` `файл:символ` `` в компаньоне или в спутнике спека — место, где утверждение исполняется                                                           |
+| Спутник                   | Файл рядом со спеком или правилом: компаньон, перечень сценариев                                                                                            |
+| Договорённость о продукте | Как продукт себя поведёт, записанное до кода. Единственное место, где спек говорит о будущем; после выкатки вливается в спек домена, а директория удаляется |
+| Ресурс                    | Единица того, что везёт пакет правил: закон, правило, паттерн, гард, проверка, роль, команда, конвейер, шаблон, умолчание, документ                         |
+| Раскладка                 | Перенос ресурса из пакета в дерево по его роду и настройке слоя                                                                                             |
+| Разложенный файл          | Файл в дереве с шапкой пакета. Правится не на месте, а надстройкой: правка на месте теряется на следующей раскладке                                         |
+| Надстройка                | Файл дерева, который сливается с разложенным по заголовкам разделов                                                                                         |
+
+## Работа
+
+| Термин          | Что это                                                                                                                                                                                      |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Задача          | Единица работы в очереди работ. Заводится до ветки, и номер её стоит в имени ветки и в заголовке отчёта                                                                                      |
+| Отчёт           | Заявка на слияние: то же название, что у задачи, переведённое в сделанное                                                                                                                    |
+| Очередь работ   | Доска, на которой видно состояние каждой задачи. Ветки она не видит                                                                                                                          |
+| Папка задачи    | Одна работа от разбора до слияния: разбор просьбы, замысел, ход работы. Умирает со слиянием — разбирается, и объясняющее решение уезжает в архив                                             |
+| Разбор          | Расспрос владельца до первой правки. Записывается его словами и задним числом не переписывается                                                                                              |
+| Замысел         | Файл папки задачи: след задачи и этапы с признаками готовности. После написания не правится — с ним сверяют результат при приёмке                                                            |
+| Ход работы      | Файл папки задачи: «Где стоим», решения по ходу с причинами, записи заходов. Единственное место, где отмечается сделанное. Журналом не называется                                            |
+| След задачи     | Раздел замысла: какие спеки, законы, правила и части кода работа задевает                                                                                                                    |
+| Заход           | Одна сессия работы над задачей. Работа живёт дольше одного захода, и между ними её состояние держит только ход работы                                                                        |
+| Заполнение окна | Доля места захода, которую он уже занял: вход, запись в кэш, прочитанное из кэша и вывод последнего ответа, делённые на размер окна. Не «расход» и не «бюджет»: речь о месте, а не о деньгах |
+| Передача        | Текст, которым заход закрывается: рабочее дерево, ветка, задача, где лежит ход работы, что сделано, следующий шаг, особенности захода. Кладётся вне дерева и не коммитится                   |
+| Линия работ     | Файл с порядком задач и зависимостями между ними, когда из одного разбора вышло несколько задач. Шире одной ветки                                                                            |
+| Архив           | Записи о состоявшемся: что объясняет закрытое решение. После выкатки не правится                                                                                                             |
+
+## Проверки
+
+| Термин                | Что это                                                                                                                     |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Гард                  | Хук агента, который отбивает действие до того, как оно сделано, и говорит, чем отказ снимается                              |
+| Гейт                  | Требование, которое пропускает действие один раз за сессию после того, как выполнено: загружено правило, пройдены проверки  |
+| Отказ в пользу работы | Устройство гарда, при котором любая его поломка пропускает действие. Сломанный гард не имеет права остановить работу совсем |
+| Прогон                | Запуск набора сценариев. «Тесты гоняются», а не «запускаются в работу»                                                      |
+| Сверка                | Проверка, которая ничего не правит, а называет расхождения: раскладки с пакетом, спеков с кодом, очереди работ с ветками    |
+| Замер                 | Число, снятое с работающего приложения. Взгляд на экран замером не является                                                 |
+
+## Так не пишем
+
+| Так не пишем               | Пишем так                                                                                      |
+| -------------------------- | ---------------------------------------------------------------------------------------------- |
+| спека (о тесте)            | тест — файл рядом с исходником; спек — документ. Одна буква разницы, а значения противоположны |
+| таска, тикет               | задача                                                                                         |
+| пул-реквест, мёрдж-реквест | отчёт, а действие — слияние                                                                    |
+| джоба, пайплайн            | конвейер и его шаг                                                                             |
+| хендофф                    | передача                                                                                       |
+| бэклог                     | очередь работ                                                                                  |
+| контекст-виндоу            | окно захода, а его доля — заполнение окна                                                      |
+| скилл, скилы               | правило, паттерн или скил без закона — по тому, что это на самом деле                          |