@rt-tools/agent-kit 0.5.0 → 0.5.1

package/assets/docs/GLOSSARY.md

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

package/assets/hooks/window-fill-guard.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# rt-hook: PostToolUse .*
+# rt-hook: PreToolUse .*
+# Заполнение окна: заход доводится до логической точки заранее, а не обрывается на середине.
+#
+# Зачем именно так. Место, где исполнитель помнит ход работы, ограничено, и заполнив его, он
+# теряет не последнее действие, а всю картину разом. Изнутри захода этот предел не виден ничем:
+# ни одна проверка дерева его не показывает, а сжатие контекста срабатывает, когда доводить
+# работу до точки уже нечем.
+#
+# Гард стоит на двух событиях сразу — разводить его по двум файлам значило бы держать два
+# разбора одной записи и два места, где правится один порог:
+#   PostToolUse — на первом пороге отдаёт напоминание: пора выбирать точку остановки;
+#   PreToolUse  — на втором отбивает всё, кроме записи хода работы, передачи и команд поставки.
+# Место между порогами и есть то, на что закрывается заход: дописать ход работы, написать
+# передачу, закоммитить проверенное.
+#
+# Размер окна берётся из настройки дерева. Из записи захода он не выводится: модель записана
+# там без пометки о расширенном окне, и заход на широкое окно от захода на узкое неотличим.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: нет размера окна, нет записи захода, нет разборщика, битый разбор —
+# работа РАЗРЕШАЕТСЯ (exit 0). Сломанный гард не имеет права заклинить работу.
+
+input="$(cat 2>/dev/null)"
+[ -z "$input" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Профиль дерева: размер окна, пороги, каталоги задач и передачи. Дерево, не задавшее размера
+# окна, стража не получает — считать долю не от чего.
+rt_hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for profile in "$rt_hooks_dir/../rt-kit/defaults/project.sh" "$rt_hooks_dir/../defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/project.sh"; do
+    # shellcheck disable=SC1090
+    [ -f "$profile" ] && . "$profile" 2>/dev/null
+done
+
+window="${RT_WINDOW_TOKENS:-}"
+case "$window" in
+    '' | *[!0-9]*) exit 0 ;;
+esac
+[ "$window" -gt 0 ] 2>/dev/null || exit 0
+
+warn_pct="${RT_WINDOW_WARN_PCT:-40}"
+stop_pct="${RT_WINDOW_STOP_PCT:-50}"
+tasks_dir="${RT_TASKS_DIR:-docs/tasks}"
+handoff_dir="${RT_HANDOFF_DIR:-.claude/handoff}"
+
+event="$(printf '%s' "$input" | jq -r '.hook_event_name // empty' 2>/dev/null)"
+transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null)"
+[ -n "$transcript" ] || exit 0
+[ -f "$transcript" ] || exit 0
+
+# Заполнение — это последняя запись ответа с расходом: вход, разовая запись в кэш, прочитанное
+# из кэша и вывод. Сумма по всем записям тут не годится вовсе — прочитанное из кэша повторяется
+# в каждой из них, и сумма выходит в разы больше окна.
+#
+# Хвост в 200 строк: запись захода растёт весь заход, а нужна из неё одна последняя строка.
+fill="$(tail -n 200 "$transcript" 2>/dev/null | jq -s -r '
+    [.[] | select(.type == "assistant") | .message.usage | select(. != null)]
+    | last
+    | if . == null then empty
+      else ((.input_tokens // 0) + (.cache_creation_input_tokens // 0)
+            + (.cache_read_input_tokens // 0) + (.output_tokens // 0))
+      end
+' 2>/dev/null)"
+
+case "$fill" in
+    '' | *[!0-9]*) exit 0 ;;
+esac
+
+pct=$((fill * 100 / window))
+fill_k=$((fill / 1000))
+window_k=$((window / 1000))
+
+# --- первый порог: напоминание, работа не отбивается -------------------------------------
+
+if [ "$event" = "PostToolUse" ]; then
+    [ "$pct" -ge "$warn_pct" ] || exit 0
+
+    # Напоминание повторяется не на каждом вызове, а на каждой следующей ступени в пять
+    # процентов: иначе оно занимает то самое место, которое бережёт.
+    step=$(((pct / 5) * 5))
+    session="$(printf '%s' "$input" | jq -r '.session_id // "unknown"' 2>/dev/null)"
+    mark_dir="${TMPDIR:-/tmp}/claude-window-fill"
+    mark="$mark_dir/$session.step"
+    mkdir -p "$mark_dir" 2>/dev/null
+    last="$(cat "$mark" 2>/dev/null)"
+    case "$last" in
+        '' | *[!0-9]*) last=0 ;;
+    esac
+    [ "$step" -gt "$last" ] || exit 0
+    printf '%s' "$step" > "$mark" 2>/dev/null
+
+    if [ "$pct" -ge "$stop_pct" ]; then
+        text="ЗАПОЛНЕНИЕ ОКНА ${pct}% (${fill_k}k из ${window_k}k) — заход закрывается сейчас. Всё, кроме записи хода работы, передачи и команд поставки, уже отбивается."
+    else
+        text="ЗАПОЛНЕНИЕ ОКНА ${pct}% (${fill_k}k из ${window_k}k). Пора выбирать точку остановки: с ${stop_pct}% останется только закрыть заход. Доведи текущий шаг до состояния, с которого следующий заход продолжит, перепиши «Где стоим» в ходе работы, напиши передачу и отдай владельцу путь к ней — паттерн task-flow-handoff."
+    fi
+
+    jq -n --arg t "$text" \
+        '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$t}}' 2>/dev/null
+    exit 0
+fi
+
+# --- второй порог: работа отбивается, закрытие захода пропускается ------------------------
+
+[ "$event" = "PreToolUse" ] || exit 0
+[ "$pct" -ge "$stop_pct" ] || exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+
+allowed=0
+case "$tool" in
+    # Разговор с владельцем и чтение того, что правится при закрытии.
+    AskUserQuestion | TodoWrite | Read | SendUserFile)
+        allowed=1
+        ;;
+    Edit | Write | MultiEdit | mcp__webstorm__create_new_file)
+        # Ход работы и передача. Остальное — работа, а её заход уже не начинает.
+        case "$path" in
+            "$tasks_dir"/* | */"$tasks_dir"/* | "$handoff_dir"/* | */"$handoff_dir"/* | */scratchpad/*) allowed=1 ;;
+        esac
+        ;;
+    Bash | mcp__webstorm__execute_terminal_command)
+        # Поставка и сверки: коммит, пуш, отчёт, колонка задачи, состояние дерева. Список
+        # дописывается профилем дерева — клиент хостинга и имена команд у каждого свои.
+        if command -v rt_handoff_allowed_cmd >/dev/null 2>&1 && rt_handoff_allowed_cmd "$cmd"; then
+            allowed=1
+        fi
+        ;;
+esac
+
+[ "$allowed" -eq 1 ] && exit 0
+
+reason="BLOCKED by window-fill-guard: заполнение окна ${pct}% (${fill_k}k из ${window_k}k), порог остановки ${stop_pct}%. Заход дальше не работает — он закрывается.
+
+Что осталось сделать этим заходом:
+1. Перепиши раздел «Где стоим» в ходе работы и добавь запись захода — что сделано, чем подтверждено, что не вышло.
+2. Закоммить проверенное: незакоммиченное не переживёт перерыв.
+3. Напиши передачу в ${handoff_dir}/ и отдай владельцу путь к ней — что в неё входит, говорит паттерн task-flow-handoff.
+
+Пропускаются при этом: правка ${tasks_dir}/**, запись передачи, команды поставки и сверки, чтение файлов и вопрос владельцу."
+
+jq -n --arg r "$reason" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}' 2>/dev/null \
+    || printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"window-fill-guard: окно заполнено, заход закрывается передачей."}}\n'
+
+exit 0

package/assets/laws/code-structure.md

@@ -20,3 +20,13 @@
   причина названа рядом.
 - **Отметка об устаревании — повод убрать, а не повод оставить.** Устаревшее объявление,
   которое молча продолжает работать, переживает того, кто его пометил.
+
+## Открытые вопросы
+
+- **Q-CS-3 — имя файла без обещания рода не судится ничем.** Проверка спрашивает файл, чьё имя
+  род называет; имя из одних слов о содержимом не говорит вовсе, и назвать род обязанным можно
+  только решением о продукте.
+- **Q-CS-4 — одноступенчатое приведение остаётся непроверенным.** Запрещено обходить сверку
+  через промежуточное «неизвестно», а обычное приведение принято: часть его обязательна, и
+  запрет отбивал бы её вместе с остальным. Решение изменит, появится ли требование к причине у
+  каждого оставшегося.

package/assets/laws/delivery.md

@@ -16,7 +16,14 @@
   которая в одну ветку не влезает, делится на задачи до того, как ветка заводится. Признак
   деления — раздельный откат, а не объём: числа файлов, строк или коммитов, за которым работа
   становится двумя задачами, нет. Правка одного рода остаётся одной задачей, сколько бы файлов
-  она ни задела.
+  она ни задела. Объём захода исполнителя признаком деления не является тоже: он говорит, какого
+  размера задачу стоит заводить среди тех, что делятся законно, и не даёт делить то, что
+  откатывается только вместе.
+- **Правка самой поставки проверяется её прогоном, а не рассуждением.** Проверить её иначе
+  нечем: она исполняется только там, где выкатывает, и в среде, которой на месте работы нет — с
+  чужими правами, чужим хранилищем ключей и чужой сетью. «Проверю после слияния» решением
+  исполнителя не бывает: за этими словами стоит выкатка, которой уже не будет, если правка
+  окажется неверной. Отложить проверку может только владелец, и он говорит это словами.
 - **Две задачи, которые чинятся одной правкой, — одна задача.** Вторая стирается вместе со
   своим номером, а то, чего в первой не было, дописывается в неё до этого. Две строки об
   одной работе хуже дыры в нумерации: по ним потом не понять, что сделано, а что нет. Слить

package/assets/laws/project-documentation.md

@@ -19,6 +19,10 @@
   символ ничего не исполняет, а проверка на нём остаётся зелёной.
 - **Путь, названный в документе, существует.** Ссылка на переехавший файл читается как
   действующее указание, и следующий читатель заводит снятое заново.
+- **Указатель каталога перечисляет всё, что в каталоге лежит.** Записи, которой в указателе нет,
+  для читателя не существует: он ищет по указателю, а не обходом каталога, и заводит разбор
+  заново. Это обратная сторона предыдущей статьи — не только путь из текста ведёт в файл, но и
+  файл назван в тексте, по которому его ищут.
 - **Документ, разошедшийся с приложением, правится тогда же, когда замечено расхождение.**
   Отложенная правка не случается: расхождение перестаёт быть заметным на следующий день.
 - **Расхождение чинится в той стороне, которая неправа, и это не всегда документ.**

package/assets/laws/work-conduct.md

@@ -33,6 +33,14 @@
 - **Состояние незаконченной работы восстанавливается без участия владельца.** Иначе каждый
   перерыв стоит ему пересказа, а очередь работ показывает начатое и не говорит, что внутри
   него сделано.
+- **Заход исполнителя конечен, и его конец не совпадает с концом работы.** Место, где
+  исполнитель помнит ход работы, ограничено; заполнив его, он теряет не последнее, а всё
+  сразу. Заход, доведённый до логической точки заранее, стоит одной записи; оборванный на
+  середине — целого захода на восстановление.
+- **Прерванная работа передаётся следующему заходу готовым текстом, а не пересказом
+  владельца.** Владелец знает, что работа не кончена, но не знает, где именно она стоит;
+  пересказ он даёт по своей памяти, а не по ходу работы, и следующий заход начинает с чужой
+  картины.
 - **Замысел и ход работы — разные записи.** Замысел — то, с чем сверяют результат при
   приёмке; правленный по ходу, он перестаёт отличаться от отчёта, и приёмке сверять нечего.
 - **Сделанное отмечается в одном месте.** Две записи об одном разъезжаются молча, и после

package/assets/patterns/spec-driven-domain.md

@@ -89,6 +89,18 @@ docs/specs/<домен>/
 `Не покрыто: <причина>`, сценарий с неполным тестом — `Покрытие: частичное — <чего не
 хватает>`.
 
+Номер в идентификаторе живёт так:
+
+| Что случилось           | Что делается с номером                                                                               |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| сценарий добавили       | берётся следующий свободный — наибольший выданный в домене плюс один, а не дырка в середине          |
+| обещание изменили       | номер тот же, заголовок теста правится тем же коммитом                                               |
+| сценарий удалили        | номер остаётся пустым и новому сценарию не отдаётся; тест удаляется вместе со сценарием              |
+| номера захотелось сжать | не пересчитываются: связь с тестами держит только номер, а прогон остаётся зелёным при обеих правках |
+
+Номер записывается так же, как у соседей в этом же файле: сверка ищет его шаблоном, и номер,
+записанный иначе, не совпадёт ни в спеке, ни в заголовке теста.
+
 ## Порядок работы
 
 1. Задача заводится сценариями: что станет верно, когда работа закончится.
@@ -121,3 +133,10 @@ docs/specs/<домен>/
 - Закон, названный в тексте, но забытый в строке `**Законы:**`: по закону тогда не узнать,
   какие домены на нём стоят.
 - Правка `.proto` без спеков задетых доменов: `docs-guard` отбивает такой коммит.
+- **Выросший домен делится на поддомены, а не на новые домены.** Новый домен пришлось бы
+  заводить в указателе, сверять с кодом отдельно и объяснять, чем он соседу не поддомен;
+  поддомен остаётся в своём домене и наследует его контракт. Соседний домен заводится только
+  тогда, когда предмет живёт своей сущностью.
+- **Границу между доменами проводит владелец, а не автор очередной правки.** Автор видит свою
+  правку, а не то, чем предмет обрастёт: домен, заведённый по ходу дела, через месяц оказывается
+  половиной соседнего, и разводить их приходится вместе с номерами сценариев.

package/assets/patterns/task-flow-close.md

@@ -15,7 +15,7 @@ description: Паттерн правила task-flow. Брать при закр
 - Этапы замысла закрыты, проверки зелёные, отчёт готовится к публикации.
 - `npm run check:specs` перечислил договорённость в разделе «Пора вливать».
 
-## 1. Договорённость вливается в спек домена
+## 9. Договорённость вливается в спек домена
 
 Последним коммитом отчёта, до слияния. Код к этому моменту написан, поэтому привязки
 `файл:символ` известны — правило въезжает в спек домена сразу проверяемым.
@@ -44,7 +44,7 @@ npm run check:specs   # раздел «Пора вливать» называе
 npm run check:specs   # после вливания: привязки на месте, сценарии не потерялись
 ```
 
-## 2. Тексты домена приводятся к сделанному
+## 10. Тексты домена приводятся к сделанному
 
 В спек уезжает только то, что записали до кода. Остальные тексты — правила, паттерны, законы
 приложения — после правки никто не перечитывает, и они продолжают описывать старое дерево.
@@ -85,7 +85,7 @@ grep -rn -A3 "Чего из закона здесь нет" <каталог пр
 Что сделали на этом шаге, пишется в тело отчёта: что перечитали, что изменили, а если ничего
 не изменили — почему. Форма раздела — паттерн `git-workflow-commit`.
 
-## 3. Папка задачи разбирается
+## 11. Папка задачи разбирается
 
 Целиком в архив не переносится: `docs/archive/` — место для записей о состоявшемся, которые
 кто-то читает, а не свалка ходов работы.
@@ -106,7 +106,7 @@ rm -r docs/tasks/<КЛЮЧ>-<номер>-<slug>
 Разбор идёт в том же отчёте, что и работа: папка, оставленная до мержа, попадает в главную
 ветку и читается там как текущая.
 
-## 4. Сверка
+## 12. Сверка
 
 ```bash
 npm run check:board   # папка закрытой задачи среди текущих, брошенные черновики

package/assets/patterns/task-flow-handoff.md

@@ -0,0 +1,115 @@
+---
+name: task-flow-handoff
+kind: pattern
+rule: task-flow
+description: Паттерн правила task-flow. Брать, когда заход упирается в заполнение окна — выбор точки остановки, запись хода работы, форма передачи и что владелец с ней делает. Не брать для возвращения к работе новым заходом — это паттерн task-flow-resume.
+---
+
+# Закрытие захода по заполнению окна
+
+Паттерн правила `task-flow`. Что при этом должно быть верно — закон
+`docs/constitution/work-conduct.md`.
+
+## Когда брать
+
+- Пришло напоминание о заполнении окна.
+- Работа не влезает в заход, и это стало видно заранее.
+- Заход прерывается по любой другой причине: владелец уходит, машина занята.
+
+## Что происходит на порогах
+
+| Заполнение          | Что делает гард                                              | Что делает заход                                      |
+| ------------------- | ------------------------------------------------------------ | ----------------------------------------------------- |
+| до первого порога   | молчит                                                       | работает                                              |
+| первый порог и выше | напоминание на каждой следующей ступени в пять процентов     | выбирает точку остановки и доводит до неё текущий шаг |
+| второй порог и выше | отбивает всё, кроме папки задачи, передачи и команд поставки | закрывается                                           |
+
+Пороги сторожит гард заполнения окна; размер окна он берёт из настройки дерева — из записи
+захода тот не выводится. Место между порогами и есть то, на что заход закрывается: дописать ход
+работы, написать передачу, закоммитить и открыть отчёт, если работа кончена.
+
+## Точка остановки
+
+Логическая точка — не «где застало напоминание», а состояние, с которого следующий заход
+продолжит, ничего не переделывая:
+
+- этап замысла закрыт целиком, а не наполовину;
+- то, что сделано, проверено — прогон прошёл, сборка собрана, замер снят;
+- проверенное закоммичено: незакоммиченное не переживёт перерыв;
+- начатое и брошенное названо в ходе работы прямо, вместе с причиной.
+
+Незакрытый этап — тоже законная точка, если в ходе работы записано, что именно из него сделано и
+чем это подтверждено. Незаконная точка одна: правка, о которой не записано ничего.
+
+## 8. Заход закрывается передачей
+
+Уборку этого шага — главную ветку, влитые ветки и запись самой передачи — делает команда
+`next-session`: она проходит его целиком и называет путь к передаче последней строкой. Ниже —
+что при этом должно получиться; порядок один и тот же, зовут его командой или руками.
+
+### Ход работы
+
+Раздел «Где стоим» перезаписывается, решения по ходу и запись захода дописываются. Форма —
+паттерн `task-flow-resume`.
+
+### Коммит
+
+Проверенное коммитится сразу, а не копится до конца задачи. Работа кончена — открывается отчёт:
+паттерн `git-workflow-commit`.
+
+### Передача
+
+Кладётся вне дерева, одним файлом на ветку — каталог передачи называет профиль дерева:
+
+```bash
+mkdir -p <каталог передачи>
+# файл — <каталог передачи>/<ветка>.md
+```
+
+Внутри — готовый текст для вставки в новый заход, без обращения к владельцу за подробностями:
+
+```markdown
+Работа: <КЛЮЧ>-<номер> «<название задачи>». Рабочее дерево — <полный путь>, ветка
+<КЛЮЧ>-<номер>-<slug> (заведена, в работе).
+
+Ход работы и замысел придут на запуске сессии хуком — перечитывать их файлами не надо. Разбор
+просьбы владельца лежит в папке задачи и читается, когда непонятна причина решения.
+
+Сделано: этапы 1–3 замысла закрыты и закоммичены.
+Следующий шаг: этап 4 — <что именно>.
+
+Что учесть в этом заходе:
+
+- стенды уже подняты владельцем, свой не поднимать;
+- зависимости этого дерева отстают от главной ветки — при падении сборки на чужой ошибке
+  сперва установка зависимостей;
+- <прочее, чего нет ни в правилах, ни в ходе работы>.
+```
+
+Разделы фиксированы, и порядок у них тот же:
+
+1. **Работа** — номер задачи, её название, рабочее дерево полным путём, ветка и её состояние.
+2. **Где искать** — что придёт хуком само, а что читается по надобности.
+3. **Сделано и следующий шаг** — одной строкой каждое; подробности уже в ходе работы.
+4. **Что учесть** — особенности этого захода, которых нет ни в правилах, ни в ходе работы:
+   поднятые стенды, отставшие зависимости, чужие процессы на портах, незакрытые вопросы к
+   владельцу.
+
+### Путь владельцу
+
+Последнее действие захода — назвать владельцу путь к передаче, чтобы он вставил текст в новый
+заход одной вставкой. Пересказывать содержание передачи в ответе не надо: владелец её и так
+прочитает, а место на неё уже потрачено.
+
+## Ловушки
+
+- **Заход закрывается на втором пороге, а не начинает на нём новый этап.** Напоминание на
+  первом — это уже сигнал выбирать точку, а не работать дальше, пока не отобьют.
+- **Передача пишется как пересказ переписки.** В неё идёт то, чего нет ни в ходе работы, ни в
+  правилах: дерево, ветка, состояние стендов. Всё остальное следующий заход прочитает сам.
+- **Состояние работы в передачу не переезжает.** Сделанное отмечается в ходе работы — одной
+  записью; передача его пересказывает, но не заменяет и в дерево не коммитится.
+- **Незакоммиченное не названо.** Работа живёт в дереве неделями, и строка «что лежит
+  несохранённым и почему» — единственное, по чему это видно.
+- **Заход, кончившийся ничем, тоже пишет передачу.** «Пробовали так — не вышло, потому что» —
+  это и есть его результат; без записи следующий заход повторит тот же путь.

package/assets/patterns/task-flow-resume.md

@@ -32,7 +32,7 @@ description: Паттерн правила task-flow. Брать при возв
   ней проверяется деревом — сборкой, тестами, чтением файла, — а не вопросом.
 - **Не править замысел.** С ним сверяют результат; пересмотр идёт записью в ходе работы.
 
-## Первое действие захода
+## 6. Возвращение к работе новым заходом
 
 Сверить «Где стоим» с деревом. Запись описывает день, когда её сделали:
 
@@ -44,7 +44,7 @@ git log --oneline origin/main..HEAD
 Разошлось — «Где стоим» правится сразу, до работы: следующий заход поверит записи, а не
 дереву.
 
-## Как ведётся ход работы
+## 7. Этап делается и отмечается в ходе работы
 
 Раздел «Где стоим» **перезаписывается**, а не дописывается — это первое, что читает следующий
 заход, и единственное, что переживает обрезку по объёму:

package/assets/patterns/task-flow-start.md

@@ -17,6 +17,10 @@ description: Паттерн правила task-flow. Брать в начале
 
 ## Порядок
 
+Шаги ниже — начало сплошного счёта: номер шага один на весь путь работы и в следующем паттерне
+не начинается заново. Весь список — в правиле `task-flow`; он же показывается владельцу в начале
+работы, чтобы после шести вопросов было видно, что впереди.
+
 ### 1. Разведка — до первого вопроса
 
 Вопрос, ответ на который лежит в коде, владельцу не задаётся: он обесценивает и остальные.

package/assets/rules/doc-style.md

@@ -34,8 +34,26 @@ description: Правило под «Закон о документации пр
   которые едут в репозиторий: личный черновик, закрытый `.gitignore` или
   `.git/info/exclude`, проверка не читает — мёртвая ссылка в нём держала гейт пуша, хотя ни
   в одну ветку этот файл не попадёт.
+- **Голое имя и каталог судятся наравне с полным путём.** Имя без каталога ищется по всему
+  дереву, каталог — среди каталогов; дерево спрашивается у системы контроля версий, иначе
+  каталоги, начинающиеся с точки, не видны и всё, что в них лежит, читалось бы как
+  несуществующее. Половина строк в таблицах «Где это лежит» — как раз каталоги.
 - **Описание прошлого из проверки путей выведено целиком.** Архив по устройству называет
-  файлы, которых уже нет, и правкой это не лечится.
+  файлы, которых уже нет, и правкой это не лечится. Папка задачи выведена по той же причине:
+  раздел находок в ходе работы перечисляет ровно то, чего в дереве нет.
+- **Переносимый текст из сверки адресов выведен, как архив.** Закон, правило и паттерн написаны
+  для любого дерева этого класса, и адреса в них принадлежат тому дереву, куда текст ложится:
+  `libs/common/util` там, где корни зовутся иначе, — пример, а не мёртвая ссылка. Разложенную
+  копию проверка узнаёт по шапке раскладки, исходник — по каталогу, названному в настройке; без
+  этого сверка краснеет на полторы сотни строк, ни одна из которых не чинится здесь.
+- **Указатель каталога сверяется с его содержимым обеими сторонами.** Записи каталог набирает
+  быстрее, чем читают его указатель, и промах не виден ни в сборке, ни в браузере: запись,
+  приехавшая слиянием соседней ветки, просто не попадает в таблицу. Сверенный руками указатель
+  расходится снова через сутки.
+- **Имя, названное затем, чтобы сказать «его нет», стоит в списке исключений поимённо.**
+  Отличить такое упоминание от ссылки машине нечем, а текст без него теряет смысл: правило и
+  замысел предупреждают именно о снятом. Туда же — то, что появляется только после сборки,
+  имена веток и правила линтеров: выглядят адресом, адресом не являются.
 - **Документ едет в том же коммите, что и правка, которую он описывает.** Обход — строка
   `Docs-skip: <причина>` в теле коммита; пустая причина не принимается.
 
@@ -57,6 +75,19 @@ description: Правило под «Закон о документации пр
 - `doc-style-write` — как формулировать: примеры «так» и «не так», правила для комментариев.
 - `doc-style-sweep` — разбор документа, накопившего список работ, на действующее и закрытое.
 
+## Скилы дерева
+
+Здесь дерево перечисляет свои скилы о документах — строка на скил: как он называется и какие
+документы ведёт. У пакета этот раздел пуст: свои документы бывают только у дерева.
+
+Раздел заведён затем, чтобы такому списку было куда встать. Дописанный в чужой раздел, он
+уносит его с собой: надстройка сливается по заголовку `## ` и замещает пакетный раздел целиком,
+поэтому приписка к «Ловушкам» стирает те пакетные пункты, которых дерево не переписывало, и
+пропажу не видно ничем.
+
+Читается этот список раньше остального: правило говорит, как формулировать, а скил дерева — что
+у документа этого рода обязательно есть, вплоть до второго файла рядом.
+
 ## Ловушки
 
 - **Оставшаяся работа не записывается в документ, а заводится задачей.** `docs/BACKLOG.md`
@@ -105,6 +136,13 @@ description: Правило под «Закон о документации пр
   выборке руками до того, как его называют: разбор, не знающий второй формы записи, ошибается
   молча — «51 пункт без задачи» оказался шестью, потому что номер стоял и отдельной строкой, и
   в заголовке подраздела.
+- **Названная в тексте проверка запускается, а не пересказывается.** «Проверка есть» и
+  «проверка проходит» — разные утверждения, и второго в тексте обычно нет вовсе. Из четырёх
+  проверок, названных правилом, три оказались не в том состоянии, в каком текст их описывает:
+  одна отдавала полтора десятка замечаний, вторая переписывала файлы самим запуском, третья
+  была красной и роняла общую сводку вместе с собой. Ни одна из трёх не входила в выкатку,
+  поэтому молчание было полным. Проверку, которая переписывает файлы, запускают на чистом
+  дереве: иначе её правки уедут чужим коммитом.
 - **Сделанность читается по дереву, а не по тексту, который о ней написан.** Это верно в обе
   стороны: строка про README обеих либ была вычеркнута как сделанная, а README остался с
   прежним числом импортёров; задача, названная владельцу несделанной, оказалась наполовину

package/assets/rules/git-workflow.azure.md

@@ -114,3 +114,27 @@ description: Правило под «Закон о поставке» для д
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится вторым рабочим элементом, здесь нет: делится то, что придётся откатывать порознь.
+  Сплошная правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать
+  два рабочих элемента, закрывать два PR и переносить коммиты по одному с двумя конфликтами.
+  Одна из трёх не дала коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей
+  под ветку тоже.
+- **Рабочий элемент заводится командой, а не вызовами подряд.** Доска показывает элементы своей
+  области и итерации, и заведённый мимо них в очереди работ не виден: со стороны это выглядит
+  так же, как незаведённый. Команда заведения ставит все поля разом — род, состояние,
+  исполнителя, область и итерацию, — и печатает готовую строку заведения ветки. Замеченный по
+  ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.