@rt-tools/agent-kit 0.14.0 → 0.16.0

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

@@ -36,6 +36,13 @@ const DEFAULTS = {
     docsDir: 'docs',
     /** Отложенное: про него проверки молчат — оно описывает прошлое, а не дерево. */
     archiveDir: 'docs/archive/',
+    /**
+     * Сколько суток живёт запись описания прошлого. `null` — срок не назначен, и тогда молчат
+     * обе стороны: сверка не краснеет, чистка не снимает. Умолчания у срока нет намеренно —
+     * пакет, назначивший его за дерево, начал бы сносить чужой архив в день установки, а
+     * снимается там разбор просьбы, которого нет больше нигде.
+     */
+    archiveRetentionDays: null,
     /**
      * Каталоги, чей указатель сверяется с содержимым: обзорный документ в них перечисляет
      * записи таблицей, и читатель ищет по ней, а не обходом. Пусто — сверки указателя нет.
@@ -80,6 +87,19 @@ const DEFAULTS = {
      * только это число.
      */
     proseSizeLimit: 300,
+    /**
+     * Предел веса текста слоя правил — в знаках. Строки меряют, сколько текста помещается на
+     * экран; веса они не меряют вовсе: правило о заявках занимает 282 строки при 13 595 знаках,
+     * а правило поставки — 272 строки при 21 508. Сжатие слоя срезает знаки и оставляет число
+     * переносов прежним, поэтому строковый предел достигнутого не закрепляет, и текст отрастает
+     * обратно молча.
+     *
+     * Число назначено по сжатому слою: самое тяжёлое правило весит 21 508 знаков, и предел стоит
+     * чуть выше него. Ниже ставить нельзя — это потребовало бы резать заново то, что уже прошло
+     * сжатие; выше незачем — тогда он ничего не закрепляет. Ноль выключает проверку веса вовсе:
+     * дерево, не назвавшее числа, судится по-прежнему одними строками.
+     */
+    proseCharLimit: 22000,
     /**
      * Корни, под которыми лежит текст слоя правил, и его источники. Файл отсюда судится
      * пределом текста, всё остальное — пределом кода. Пусто — предел один на всё дерево.
@@ -258,7 +278,10 @@ export const parseAllowlist = (name, sides = ['accepted', 'debt']) => {
             return new Map();
         }
         if (Array.isArray(entries) || typeof entries !== 'object' || entries === null) {
-            refuse(`«${side}» записан не объектом — у записи нет места ни для причины, ни для номера задачи`);
+            refuse(
+                `«${side}» записан не объектом — у записи нет места ни для причины, ни для номера задачи. ` +
+                    `Форма: {"${side}": {"<ключ>": {"reason": "<почему>", "task": "${key || 'КЛЮЧ'}-<номер>"}}}`,
+            );
         }
         const parsed = new Map();
         for (const [entry, value] of Object.entries(entries)) {

package/assets/checks/spec-anchors.mjs

@@ -108,7 +108,11 @@ function checkRuleImplementation(specFile, text, mapFile, heading = '## Прав
 
     const rows = new Map();
     for (const line of rowsOfMap(specFile, mapFile, mapHeading)) {
-        const cells = line.match(/^\|([^|]+)\|([^|]*)\|\s*$/);
+        // Привязка записывается двумя формами, и читаются обе. Таблица — прежняя; список — та,
+        // ради которой из компаньонов уходят пробелы выравнивания: форматтер добивает столбцы до
+        // общей ширины, и в компаньонах дерева это 120 017 знаков из 328 738, то есть 37%.
+        // Связь при этом не меняется: она идёт по тексту утверждения, а не по форме строки.
+        const cells = line.match(/^\|([^|]+)\|([^|]*)\|\s*$/) ?? line.match(/^-\s+\*\*(.+?)\*\*\s+—\s+(.*)$/);
         if (!cells) {
             continue;
         }
@@ -210,8 +214,14 @@ function symbolOwners() {
 
     for (const file of SOURCE_ROOTS.flatMap((root) => walk(root, (name) => name.endsWith('.ts') || name.endsWith('.html')))) {
         const text = file.endsWith('.ts') ? codeOf(read(file)) : read(file);
-        for (const [token] of text.matchAll(/[A-Za-z_][\w-]*/g)) {
+        // Решётка входит в токен: приватное поле класса объявлено с ней, и якорь на него иначе
+        // не попадал бы в перечень владельцев ни разу. Имя без решётки помнится наравне с ним
+        // самим — привязки прежней формы остаются зелёными, и переходить разом не приходится.
+        for (const [token] of text.matchAll(/#?[A-Za-z_][\w-]*/g)) {
             remember(token, file);
+            if (token.startsWith('#')) {
+                remember(token.slice(1), file);
+            }
             if (token.includes('-')) {
                 token.split('-').forEach((part) => part && remember(part, file));
             }
@@ -242,7 +252,12 @@ function checkTracedAnchors() {
 
     const owners = symbolOwners();
     for (const { mapFile, path, symbol } of declared) {
-        const here = (codeAt(path).match(new RegExp(`\\b${escapeForRegExp(symbol)}\\b`, 'g')) || []).length;
+        // Граница слова ставится только там, где она есть: перед решёткой её нет, и образец с
+        // ней давал бы ноль вхождений у всякого приватного имени.
+        const bound = symbol.startsWith('#')
+            ? `${escapeForRegExp(symbol)}\\b`
+            : `\\b${escapeForRegExp(symbol)}\\b`;
+        const here = (codeAt(path).match(new RegExp(bound, 'g')) || []).length;
         const elsewhere = [...(owners.get(symbol) || [])].filter((file) => file !== path).length;
         if (here + elsewhere < 2) {
             report(

package/assets/checks/spec-common.mjs

@@ -66,8 +66,12 @@ const E2E_ROOTS = CONFIG.e2eRoots;
  * переписан целиком. Алфавит не перечисляется диапазонами: перечисленные молча не покрывают
  * соседнего, и промах выглядит отсутствием привязки. Путь при этом остаётся латинским — он
  * адрес в дереве, а не слово текста.
+ *
+ * Решётка перед именем законна: приватное поле класса объявлено с ней, и записанное без неё имя
+ * называет метод не тем именем, каким он объявлен. Проверка при этом остаётся зелёной — граница
+ * слова перед решёткой есть, — поэтому промах не краснеет ни разу и виден только чтением.
  */
-const ANCHOR = /`([\w./-]+\.[A-Za-z]{2,10}):(\p{L}[\p{L}\p{N}_-]*|_[\w-]*)`/gu;
+const ANCHOR = /`([\w./-]+\.[A-Za-z]{2,10}):(#?\p{L}[\p{L}\p{N}_-]*|#?_[\w-]*)`/gu;
 /**
  * Явный вердикт вместо якоря: статья, которой в дереве исполняться негде. Так бывает
  * законно — правило говорит о службе, которой дерево не держит, или о движении человека,

package/assets/defaults/project.sh

@@ -88,7 +88,7 @@ rt_push_checks_default() {
 
     for check in check-doc-paths check-specs check-file-size check-dupes check-styles \
         check-lib-layers check-reuse check-schema-drift check-states check-state-next \
-        check-turn-map check-push-gate; do
+        check-turn-map check-archive-age check-push-gate; do
         [ -f "$root/$RT_CHECKS_DIR/$check.mjs" ] && printf '%s\n' "node $RT_CHECKS_DIR/$check.mjs"
     done
 
@@ -258,24 +258,29 @@ rt_shell_writes_default() {
 # Судится заголовок команды — именно в нём стоит тот путь, куда команда пишет.
 #
 # Исключение — интерпретатор: ему код приходит телом, и путь записи стоит именно там. Признак
-# ошибается в сторону лишнего чтения тела: имя интерпретатора, стоящее в команде где угодно,
-# возвращает разбор тела целиком.
+# читается у той строки, которая тело открыла, а не у всей команды: тело принадлежит команде
+# своего заголовка. Прежде он читался у всего текста разом, и слово из документа отключало
+# вырезание целиком — строка «**Чем проверяется:** `bash projects/…`» в замысле делала запись
+# `plan.md` правкой кода приложения. Гард отбивал тем самым запись того файла, отсутствием
+# которого он же и отказывает.
 rt_shell_paths_default() {
     text="$(printf '%s' "$1" | tr "\"'\`" '   ')"
-    if ! printf '%s' "$text" \
-        | grep -Eq '(^|[|;&(]|[[:space:]])(python3?|node|ruby|perl|php|deno|bun|bash|sh|zsh)([[:space:]]|$)'; then
-        text="$(printf '%s' "$text" | awk '
-            function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
-            tag != "" { if (trim($0) == tag) tag = ""; next }
-            {
-                print
-                if (match($0, /<<-?[ \t]*[A-Za-z_][A-Za-z0-9_]*/)) {
-                    t = substr($0, RSTART, RLENGTH)
-                    sub(/^<<-?[ \t]*/, "", t)
-                    tag = t
-                }
-            }')"
-    fi
+    text="$(printf '%s' "$text" | awk '
+        function trim(s) { sub(/^[ \t]+/, "", s); sub(/[ \t]+$/, "", s); return s }
+        tag != "" {
+            if (keep) { print }
+            if (trim($0) == tag) { tag = ""; keep = 0 }
+            next
+        }
+        {
+            print
+            if (match($0, /<<-?[ \t]*[A-Za-z_][A-Za-z0-9_]*/)) {
+                t = substr($0, RSTART, RLENGTH)
+                sub(/^<<-?[ \t]*/, "", t)
+                tag = t
+                keep = ($0 ~ /(^|[|;&(]|[ \t])(python3?|node|ruby|perl|php|deno|bun|bash|sh|zsh)([ \t]|$)/)
+            }
+        }')"
 
     # Пути берутся только у тех кусков команды, которые пишут. Прежде брались у всей строки
     # целиком, и команда чтения, сцепленная с записью, отдавала свои пути как цели записи:

package/assets/defaults/turn-map.md

@@ -9,19 +9,17 @@
 
 ## Состояния и обязательные действия
 
-| Состояние                 | Обязательное действие                                  | Ведёт паттерн      |
-| ------------------------- | ------------------------------------------------------ | ------------------ |
-| `просьба-не-разобрана`    | разведка по дереву, затем вопросы                      | `task-flow-start`  |
-| `разбор-закрыт`           | договорённость о продукте либо причина её отсутствия   | `task-flow-start`  |
-| `договорённость-записана` | завести задачу, ветку и папку                          | `task-flow-start`  |
-| `задача-взята`            | написать замысел                                       | `task-flow-start`  |
-| `замысел-записан`         | делать первый этап                                     | `task-flow-start`  |
-| `этап-идёт`               | доделать этап и отметить в ходе работы                 | `task-flow-resume` |
-| `этапы-кончились`         | прогнать набор и открыть PR черновиком                 | `task-flow-close`  |
-| `работа-отдана`           | взять следующую задачу                                 | `task-flow-resume` |
-| `разбор-кончился`         | влить договорённость, привести тексты, разобрать папку | `task-flow-close`  |
-| `папка-разобрана`         | снять черновик и попросить влить                       | `task-flow-archive` |
-| `влито`                   | разбор работы правилами и сверка очереди               | `task-flow-archive` |
+- `просьба-не-разобрана` — разведка по дереву, затем вопросы; ведёт `task-flow-start`
+- `разбор-закрыт` — договорённость о продукте либо причина её отсутствия; ведёт `task-flow-start`
+- `договорённость-записана` — завести задачу, ветку и папку; ведёт `task-flow-start`
+- `задача-взята` — написать замысел; ведёт `task-flow-start`
+- `замысел-записан` — делать первый этап; ведёт `task-flow-start`
+- `этап-идёт` — доделать этап и отметить в ходе работы; ведёт `task-flow-resume`
+- `этапы-кончились` — прогнать набор и открыть PR черновиком; ведёт `task-flow-close`
+- `работа-отдана` — взять следующую задачу; ведёт `task-flow-resume`
+- `разбор-кончился` — влить договорённость, привести тексты, разобрать папку; ведёт `task-flow-close`
+- `папка-разобрана` — снять черновик и попросить влить; ведёт `task-flow-archive`
+- `влито` — разбор работы правилами и сверка очереди; ведёт `task-flow-archive`
 
 Ни у одного состояния обязательное действие не звучит как «ждать». Прогон, разбор владельцем и
 слияние идут без исполнителя и от взгляда быстрее не становятся.
@@ -30,12 +28,10 @@
 
 Способов четыре, и других нет.
 
-| Выход                                              | Чем подтверждается                                              |
-| -------------------------------------------------- | --------------------------------------------------------------- |
-| вопрос владельцу, ответа на который в правилах нет | вопрос задан, и за тот же ход правила читались                  |
-| отказ гарда                                        | отказ назван владельцу, обход не искался                        |
-| заполненное окно там, где сжатия нет               | ход работы дописан, передача написана                           |
-| работа отдана, и следующая начата                  | PR открыт, и по следующей задаче сделано действие, а не сказано |
+- **вопрос владельцу, ответа на который в правилах нет** — вопрос задан, и за тот же ход правила читались
+- **отказ гарда** — отказ назван владельцу, обход не искался
+- **заполненное окно там, где сжатия нет** — ход работы дописан, передача написана
+- **работа отдана, и следующая начата** — PR открыт, и по следующей задаче сделано действие, а не сказано
 
 Там, где дерево объявило порог сжатия ниже порога остановки, заполненное окно ход не кончает:
 контекст сжимается, передача приходит входом, и работа идёт дальше тем же заходом. Порог

package/assets/docs/GLOSSARY.md

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

package/assets/hooks/rule-article.sh

@@ -75,6 +75,18 @@ rt_rule_article_marks() {
 # Текст статьи, внутри которой стоит строка с признаком. Статья начинается ближайшим сверху
 # пунктом списка верхнего уровня и кончается перед следующим таким пунктом или перед строкой без
 # отступа: продолжение статьи всегда идёт с отступом.
+# Заголовок статьи — её жирная первая фраза. Отказ гейта называет статьи ею, а не пересказывает
+# их телом: правило заход грузит следом, и тело придёт в контекст вторым разом. У правила текстов
+# отказ печатал 4 134 знака одиннадцатью статьями, их заголовки — 718.
+#
+# Заголовок при этом не украшение: по нему идёт привязка утверждения к коду, и он же называет
+# статью в отказе так, что её видно в правиле глазами.
+rt_rule_article_heads() {
+    rule_file="$1"
+    edited="$2"
+    rt_rule_articles "$rule_file" "$edited" 2>/dev/null | grep -o '^- \*\*[^*]*\*\*' 2>/dev/null
+}
+
 rt_rule_article_at() {
     awk -v mark="$2" '
         NR <= mark && /^- / { start = NR }

package/assets/hooks/skill-gate.sh

@@ -186,13 +186,14 @@ fi
 # Правило целиком остаётся вторым ходом — для того, кому статьи мало.
 # shellcheck disable=SC1090
 [ -f "$rt_hooks_dir/rule-article.sh" ] && . "$rt_hooks_dir/rule-article.sh" 2>/dev/null
-if [ "$kind" != "command" ] && [ "$kind" != "browser" ] && command -v rt_rule_articles >/dev/null 2>&1; then
-    article="$(rt_rule_articles "$root/$rules_dir/${req}/SKILL.md" "$target" 2>/dev/null)"
+if [ "$kind" != "command" ] && [ "$kind" != "browser" ] && command -v rt_rule_article_heads >/dev/null 2>&1; then
+    article="$(rt_rule_article_heads "$root/$rules_dir/${req}/SKILL.md" "$target" 2>/dev/null)"
     if [ -n "$article" ]; then
-        reason="Отбито гейтом правил. Под эту правку подпадает статья правила «${req}»:
+        reason="Отбито гейтом правил. Под эту правку подпадают статьи правила «${req}»:
 
 ${article}
-Статья снимает чтение правила целиком, а не отказ: загрузи правило «${req}» инструментом Skill и повтори действие. ${fallback} Для этой области это происходит один раз за сессию."
+
+Текст этих статей придёт в контекст вместе с правилом, и пересказывать его здесь значило бы платить за один текст дважды: загрузи правило «${req}» инструментом Skill и повтори действие. ${fallback} Для этой области это происходит один раз за сессию."
     fi
 fi
 

package/assets/hooks/task-flow-guard.sh

@@ -215,6 +215,26 @@ case "$state" in
         ;;
 esac
 
+# Папка задачи едет в ветку коммитом, а не живёт в одном рабочем дереве. Четыре требования выше
+# смотрят диск, и папка, ни разу не закоммиченная, проходит их все без единого отказа — а
+# признак отданной работы гард берёт из истории, и там её нет. Отказ приходит в последней точке,
+# на открытии заявки, когда папка уже разобрана своими руками: чинить нечего, замысел снят, и
+# собирать его приходится заново по памяти. За одну задачу это стоило восьми вызовов и двух
+# отказов подряд.
+#
+# Второе следствие тише: ход работы, живущий в рабочем дереве, не виден никому. Владелец видит
+# ветку без единого следа того, что в ней делается, а следующий заход — пустоту вместо «Где
+# стоим», если рабочее дерево между заходами сменилось.
+#
+# Спрашивается та же история, что и у признака отданной работы: папка стоит в `HEAD` либо её
+# добавлял коммит ветки. Нет git — требования нет: спросить историю нечем.
+if [ -n "$(git rev-parse --verify HEAD 2>/dev/null)" ]; then
+    in_tree="$(git ls-tree -d --name-only HEAD -- "$tasks_dir/$branch" 2>/dev/null | head -1)"
+    if [ -z "$in_tree" ]; then
+        deny "BLOCKED by task-flow: папка задачи '${tasks_dir}/${branch}' лежит в рабочем дереве, а в историю ветки не заведена. Заведи её коммитом (git add ${tasks_dir}/${branch} && git commit), затем повтори: признак отданной работы гард берёт из истории, и с некоммиченной папкой отказ придёт на открытии заявки — когда папка уже разобрана и чинить нечего. Правило — скил task-flow."
+    fi
+fi
+
 # Строка обхода: поведение не меняется, договорённость о продукте не нужна. Причина обязана
 # стоять — без неё обход становится умолчанием.
 if grep -qE '^\*\*Поведение:\*\*[[:space:]]*не меняется[[:space:]]*—[[:space:]]*\S' "$plan" 2>/dev/null; then