@rt-tools/agent-kit 0.9.1 → 0.11.0

package/assets/patterns/cargo-triage-mark.md

@@ -0,0 +1,119 @@
+---
+name: cargo-triage-mark
+kind: pattern
+rule: cargo-triage
+description: Паттерн правила cargo-triage. Брать при разборе приехавшего груза — готовые вызовы отметки: сухой прогон, пачка записей за вызов, приём починки при переходе в готово, версия выпуска при выпуске, разбор отбитой строки. Не брать для сведения предложений в правки пакета — это своя команда.
+---
+
+# Отметка записей груза
+
+Паттерн правила `cargo-triage`. Что при этом должно быть верно — закон
+`docs/constitution/work-conduct.md`.
+
+Вызовы ниже идут строкой запуска самого пакета и токеном дерева: токен лежит вне дерева, и без
+него команда отбивает вызов, не ходя в сеть.
+
+## Когда брать
+
+- Разбирается приехавший груз, и по записи принято решение.
+- Правка по записи влита в главную ветку.
+- Опубликована редакция, увёзшая починку к потребителю.
+- Вызов отметки вернул отбитую строку.
+
+## Что читается раньше вызова
+
+Список неразобранного — в админке приёма, отбором по состоянию «новое» и порядком приезда.
+Пока список не сужен, разобранное и нетронутое стоят вперемешку, и разбор идёт по второму
+кругу.
+
+Имя команды, адрес приёма и слова состояний у каждого дерева свои — они названы в
+`implementation.md` правила. Ниже они стоят так, как их зовёт пакет.
+
+## Взятие в работу: задача и отметка одним ходом
+
+Сначала задача — иначе отметка говорит, что запись взяли, и молчит о том, где идёт работа:
+
+```bash
+npm run task:new -- --title '<что не так>' --slug <короткое-имя> --label bug < тело.md
+```
+
+Отметка идёт следом, тем же ходом, и несёт все записи, которые эта задача закрывает:
+
+```bash
+npx agent-kit mark --state in_work \
+    --postmortem 2026-08-14-structure-invented-beside-the-sample.md \
+    --postmortem 2026-08-15-guard-denied-shell-wrote-anyway.md \
+    --proposal <признак предложения>
+```
+
+Род записи называется своим доводом: разбор происшествия — именем файла, предложение —
+признаком текста. Записи обоих родов едут одним вызовом.
+
+Сухим прогоном смотрят, что уехало бы, — он ничего не отправляет и следа наружу не оставляет:
+
+```bash
+npx agent-kit mark --state in_work --postmortem <файл> --dry-run
+```
+
+Сухой прогон вместо настоящего вызова оставляет запись в прежнем состоянии. Отметкой он не
+считается.
+
+## Починка: переход вместе с ответом на «чем»
+
+Ставится после того, как правка влита в главную ветку, — не по открытой заявке:
+
+```bash
+npx agent-kit mark --state fixed \
+    --postmortem <файл> \
+    --fix 'заведена статья правила о разборе груза и паттерн с готовыми вызовами'
+```
+
+Текст отвечает на «чем», а не на «где»: статья правила, гард, проверка, правка кода. Без него
+строка отбивается — переход в починку без ответа на «чем» приёмник не принимает.
+
+## Выпуск: версия называется тем, кто публикует
+
+Идёт тем же движением, что и публикация редакции:
+
+```bash
+npx agent-kit mark --state released --postmortem <файл> --release 'rt-agent-kit@0.10.1'
+```
+
+Версия — та, которой назван выпуск, увёзший починку. Не номер редакции приёмника и не время
+выкатки.
+
+## Ответ читается
+
+Вызов отвечает тремя числами и списком:
+
+```
+переведено 2, уже стояло 1, отбито 1
+  строка 3: <ключ> — записи у дерева нет
+```
+
+- **Переведено 0, уже стояло N** — этот разбор не двинул ничего: записи отмечены раньше либо
+  ключи названы не те.
+- **Отбито N** — эти записи остались там, где были. Причина названа при строке, и повтор того
+  же вызова отбивается ровно так же.
+
+Причины отбоя и что делать с каждой:
+
+| Что сказано            | Что это значит                                 | Что делать                           |
+| ---------------------- | ---------------------------------------------- | ------------------------------------ |
+| записи у дерева нет    | ключ назван не тот либо запись прислало не оно | сверить ключ со списком в админке    |
+| переход не разрешён    | шаг через состояние либо ход назад             | пройти состояние, которое пропустили |
+| перехода без текста    | починка без ответа на «чем»                    | добавить довод с текстом починки     |
+| текста не при том шаге | текст приехал с переходом, который не починка  | убрать довод либо сменить состояние  |
+| перехода без версии    | выпуск без ответа на «где искать фикс»         | добавить довод с версией выпуска     |
+| версии не при том шаге | версия приехала с переходом, который не выпуск | убрать довод либо сменить состояние  |
+
+## Ловушки
+
+- **Вызов без токена отбивается без сети.** Токен лежит вне дерева, и на свежей рабочей копии
+  его нет: команда называет это прямо, а не молчит.
+- **Своё дерево называется признаком из токена, а не доводом.** Приём сверяет его сам, и
+  назваться чужим деревом вызов не может.
+- **Записи, отмеченные в одной ветке, в соседней выглядят неотмеченными только в файлах.**
+  Состояние лежит в приёме, а не в дереве: смотрят его в админке, а не в рабочей копии.
+- **Повторная отметка тем же состоянием промахом не считается.** Рабочий порядок повторяют, и
+  вторая та же отметка отбивается ответом «уже стояло», а не отказом.

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

@@ -19,7 +19,7 @@ description: Паттерн правила task-flow. Брать при закр
 кода отдаётся владельцу, — то есть до этого паттерна и, как правило, задолго до него. Здесь
 работа доводится до готовности и черновик снимается.
 
-## 10. Работа отдаётся на разбор
+## Состояние `этапы-кончились`: работа отдаётся на разбор
 
 PR открыт черновиком — и с этой минуты работа ждёт владельца, а не машину. Заход на этом не
 кончается: следующая задача эпика берётся тем же движением, паттерн `task-flow-resume`.
@@ -102,7 +102,10 @@ PR #<номер> готов к слиянию: прогон зелёный, па
 кто пишет тело. Разница между ними одна, и она вся: реплику владелец прочитает, только если
 вернётся в переписку, а раздел он видит там, куда смотрит, нажимая кнопку.
 
-## 12. Договорённость вливается в спек домена
+**Следующее движение:** тем же ходом берётся следующая задача эпика, а разбор закрытой работы
+уходит в фон. Прогон и владелец идут без исполнителя, и ждать их состоянием работы не бывает.
+
+## Состояние `разбор-кончился`: договорённость вливается в спек домена
 
 Последним коммитом PR, до слияния. Код к этому моменту написан, поэтому привязки
 `файл:символ` известны — правило въезжает в спек домена сразу проверяемым.
@@ -131,7 +134,10 @@ npm run check:specs   # раздел «Пора вливать» называе
 npm run check:specs   # после вливания: привязки на месте, сценарии не потерялись
 ```
 
-## 13. Тексты домена приводятся к сделанному
+**Следующее движение:** за влитой договорённостью тем же ходом идут тексты домена — правила,
+паттерны и разделы, которые работа задела.
+
+## Состояние `разбор-кончился`: тексты домена приводятся к сделанному
 
 В спек уезжает только то, что записали до кода. Остальные тексты — правила, паттерны, законы
 приложения — после правки никто не перечитывает, и они продолжают описывать старое дерево.
@@ -172,7 +178,10 @@ grep -rn -A3 "Чего из закона здесь нет" <каталог пр
 Что сделали на этом шаге, пишется в тело PR: что перечитали, что изменили, а если ничего
 не изменили — почему. Форма раздела — паттерн `git-workflow-commit`.
 
-## 14. Папка задачи разбирается
+**Следующее движение:** приведённые тексты коммитятся, и тем же ходом разбирается папка
+задачи — последним коммитом ветки.
+
+## Состояние `разбор-кончился`: папка задачи разбирается
 
 Разбор идёт по трём исходам, а не по двум.
 
@@ -229,7 +238,10 @@ rm -r docs/tasks/<своя>
 Две записи в архиве, а не одна: работы разные, и решения в них разные. Сверка очереди работ
 после этого не называет ни одной папки — этим и проверяется, что разобраны обе.
 
-## 15. Сверка
+**Следующее движение:** разобранная папка уезжает в ветку тем же коммитом, и следом за ним
+сверяется очередь работ.
+
+## Состояние `папка-разобрана`: сверка очереди работ
 
 ```bash
 npm run check:board   # папка закрытой задачи среди текущих, брошенные черновики
@@ -237,7 +249,10 @@ npm run check:specs   # договорённость влита, привязк
 npm run check:docs    # пути, названные в текстах, существуют
 ```
 
-## 16. Работа разбирается правилами — фоном, следом за PR
+**Следующее движение:** расхождения, названные сверками, чинятся тем же ходом; чинить нечего —
+тот же ход снимает черновик и просит владельца влить, называя номер.
+
+## Состояние `влито`: работа разбирается правилами — фоном, следом за PR
 
 Шаг о слое правил, а не о продукте: что за эту работу грузилось, что помогло, чего не хватило и
 где текст правила разошёлся с деревом. Знает это только тот заход, который работу вёл, — через
@@ -261,13 +276,16 @@ npm run check:docs    # пути, названные в текстах, суще
 3. **Вернувшиеся находки принимают одним ходом** — записать и вернуться к прежнему. Разбор,
    отложенный «до удобного момента», не случается вовсе: заход кончается раньше.
 
-## 17. Находки разбора ложатся в папку задачи и ждут владельца
+**Следующее движение:** пока роль разбирает, тот же ход занят следующей задачей; вернувшиеся
+находки принимаются одним ходом — записать и продолжить прежнее.
+
+## Состояние `влито`: находки разбора ложатся в папку задачи и ждут владельца
 
 Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск — в папку
 задачи, файлом рядом с ходом работы. Пишет его исполнитель: роль файлов не пишет.
 
 Папка задачи умирает со слиянием, а находки должны пережить весь эпик — владелец читает их
-разом, когда эпик кончился. Поэтому при разборе папки (шаг 14) файл находок не удаляется вместе
+разом, когда эпик кончился. Поэтому при разборе папки файл находок не удаляется вместе
 с остальным, а **переезжает к замыслу эпика**: там его найдут и после того, как ветка въехала.
 Работа вне эпика показывает находки владельцу сразу, тем же ходом.
 
@@ -296,6 +314,9 @@ npm run check:docs    # пути, названные в текстах, суще
 котором владелец сказал вслух, уходит наружу в тот же ход: написанное и не отправленное лежит в
 дереве неотличимо от отправленного.
 
+**Следующее движение:** записанные находки работу не держат — следующая задача уже идёт, а
+владельцу о них говорится, когда кончился эпик.
+
 ## Ловушки
 
 - **Папку разбирают до слияния — потом о ней уже никто не вспомнит.** Сверка очереди считает

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

@@ -41,7 +41,7 @@ description: Паттерн правила task-flow. Брать, когда з
 Незакрытый этап — тоже законная точка, если в ходе работы записано, что именно из него сделано и
 чем это подтверждено. Незаконная точка одна: правка, о которой не записано ничего.
 
-## 9. Заход закрывается передачей
+## Заход закрывается передачей, состояние работы при этом не меняется
 
 Уборку этого шага — главную ветку, влитые ветки и запись самой передачи — делает команда
 `next-session`: она проходит его целиком и называет путь к передаче последней строкой. Ниже —
@@ -66,6 +66,24 @@ mkdir -p <каталог передачи>
 # файл — <каталог передачи>/<ветка>.md
 ```
 
+**Черновик передачи пишет хук, а не рука.** Перед сжатием контекста он кладёт по тому же
+адресу то, что есть на диске: ветку, состояние работы, следующий шаг, незакоммиченное, коммиты
+сверх главной. Сжатие приходит и тогда, когда напомнить некому — ночью или посреди длинного
+хода, — и без хука заход в этот момент терял передачу целиком.
+
+**Читает передачу тоже хук, а не человек.** На запуске он кладёт её в контекст целиком — вместе
+с картой хода, — и вставлять её руками не приходится ни после сжатия, ни после обрыва, ни после
+очистки. Написанная и не прочитанная, передача равна ненаписанной: следующий заход о ней не
+знает и начинает с пустого места, то есть с того же, ради чего её и писали.
+
+Отсюда требование к тексту: передача пишется для машины, которая подаст её без разбора, и для
+захода, который прочтёт её первой строкой. Обращаться в ней к владельцу — «спроси у него, чем
+кончилась проба» — значит писать в пустоту: к моменту чтения владельца в разговоре ещё нет.
+
+Написанное хуком — нижняя граница, а не готовая передача. Исполнитель, закрывающий заход по
+правилу, пишет поверх: он знает то, чего на диске нет, — чем кончилась проба, почему выбран
+этот путь, что владелец сказал по дороге. Файл один, последняя запись побеждает.
+
 Внутри — готовый текст для вставки в новый заход, без обращения к владельцу за подробностями:
 
 ```markdown

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

@@ -34,7 +34,27 @@ description: Паттерн правила task-flow. Брать при возв
   ней проверяется деревом — сборкой, тестами, чтением файла, — а не вопросом.
 - **Не править замысел.** С ним сверяют результат; пересмотр идёт записью в ходе работы.
 
-## 7. Возвращение к работе новым заходом
+## Вход из передачи захода
+
+Передача написана прошлым заходом и лежит вне дерева. Её читают как задание — и берутся за
+работу мимо правила: состояние не сверено, правило не загружено, числа взяты на веру. Отличие
+входа из передачи от обычного захода одно: всё, что в ней написано, проверяется деревом, потому
+что писалась она вчера.
+
+Порядок короткий, четыре шага:
+
+1. **Правило ведения работы и этот паттерн — первым движением**, до первой реплики владельцу.
+2. **Ветка и состояние работы читаются в дереве**, а не в передаче: `git branch --show-current`
+   и строка состояния в ходе работы. Разошлось с передачей — верно дерево.
+3. **Числа из передачи пересчитываются** на текущем коммите. Оценка «работы вдвое больше» при
+   пересчёте не подтвердилась ни разу.
+4. **Следующий шаг берётся из хода работы**, а не из раздела передачи о нём: ход работы
+   коммитится, передача — нет, и разойтись они успевают за один заход.
+
+Чего в передаче нет и не будет: слов владельца — они в разборе просьбы; решений с причинами —
+они в ходе работы; замысла — он на диске. Передача пересказывает, а не заменяет.
+
+## Вход в заход: строка состояния сверяется с деревом
 
 Сверить «Где стоим» с деревом. Запись описывает день, когда её сделали:
 
@@ -44,9 +64,11 @@ git log --oneline origin/main..HEAD
 ```
 
 Разошлось — «Где стоим» правится сразу, до работы: следующий заход поверит записи, а не
-дереву.
+дереву. Строка состояния правится вместе с ним: гард читает её, и оставленная от прошлого
+захода она либо отбивает законную правку, либо пропускает работу, которая до правки кода ещё
+не дошла.
 
-## 8. Этап делается и отмечается в ходе работы
+## Состояние `этап-идёт`: этап делается и отмечается в ходе работы
 
 Раздел «Где стоим» **перезаписывается**, а не дописывается — это первое, что читает следующий
 заход, и единственное, что переживает обрезку по объёму:
@@ -54,6 +76,7 @@ git log --oneline origin/main..HEAD
 ```markdown
 ## Где стоим
 
+- **Состояние:** `этап-идёт`
 - **Этап:** 3 из 6 — гард и хук запуска
 - **Сделано:** закон заведён, папка задачи и образец написаны
 - **Следующий шаг:** сценарии обоих хуков, затем подключение в настройках
@@ -71,6 +94,9 @@ git log --oneline origin/main..HEAD
 - **PR:** #1396, ждёт разбора · отвечено 3 замечания из 5 · не сделано: разбор папки задачи
 ```
 
+С открытием PR состояние становится `работа-отдана`, и обязательное действие у него другое —
+следующая задача, а не ожидание разбора.
+
 Решение, принятое по ходу, — вместе с причиной и с тем, что было альтернативой:
 
 ```markdown
@@ -94,7 +120,10 @@ git log --oneline origin/main..HEAD
 - Доэтапное, не этой работы: сверка очереди перечисляет шесть закрытых задач вне борды.
 ```
 
-## 11. Следующая задача эпика берётся тем же движением
+**Следующее движение:** отмеченный этап тем же ходом сменяется следующим. Этапы кончились —
+тот же ход гонит набор и открывает PR черновиком.
+
+## Состояние `работа-отдана`: следующая задача берётся тем же движением
 
 Задача закрыта, PR открыт и ждёт владельца — заход на этом не кончается. Отданное на разбор
 ждёт человека, а не машину: пока эпик не кончился, следующая его задача берётся сразу, тем же
@@ -112,6 +141,9 @@ git log --oneline origin/main..HEAD
 `task-flow-handoff`. Эпик кончился — заход закрывается тем же порядком, и владельцу называется,
 что кончился именно эпик, а не одна его задача.
 
+**Следующее движение:** по следующей задаче делается действие — заведена задача, ветка или
+папка. Ход кончается после него, а не после слов о нём.
+
 ## Ловушки
 
 - **Заход, кончившийся ничем, тоже записывается.** Иначе следующий пойдёт той же дорогой:

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

@@ -21,7 +21,7 @@ description: Паттерн правила task-flow. Брать в начале
 не начинается заново. Весь список — в правиле `task-flow`; он же показывается владельцу в начале
 работы, чтобы после шести вопросов было видно, что впереди.
 
-### 1. Разведка — до первого вопроса
+### Состояние `просьба-не-разобрана`: разведка — до первого вопроса
 
 Вопрос, ответ на который лежит в коде, владельцу не задаётся: он обесценивает и остальные.
 
@@ -40,7 +40,10 @@ Agent(subagent_type: "Explore", prompt: "<тема просьбы>: что по
 считается сделанным, разведка исполняется как настроение: прочитанный переданный текст сходит
 за неё, и по текущему дереву не запускается ни одной команды.
 
-### 2. Разбор с владельцем
+**Следующее движение:** находки ложатся в разбор, и тем же ходом владельцу уходит первый из
+шести вопросов. Разведка кончилась — состояние осталось прежним, ход тоже.
+
+### Состояние `просьба-не-разобрана`: разбор с владельцем
 
 Ведёт главный агент: субагент до владельца не достучится. Команда — `/grill-me`, один вопрос
 за раз, к каждому — свой рекомендуемый ответ с доводом.
@@ -89,7 +92,10 @@ mkdir -p docs/tasks/_draft-<slug>
 cp docs/tasks/_template/grill.md docs/tasks/_draft-<slug>/grill.md
 ```
 
-### 3. Конвейер после разбора
+**Следующее движение:** ответ владельца дописывается в разбор, и следом уходит следующий
+вопрос. Ответы кончились — тем же ходом работа идёт в конвейер ролей.
+
+### Состояние `разбор-закрыт`: конвейер после разбора
 
 Вопросов больше не будет — дальше роли:
 
@@ -107,7 +113,10 @@ Workflow(name: "plan", args: "docs/tasks/_draft-<slug>")
 «не входит». Находка критика, расходящаяся с ответом владельца, относится владельцу — она не
 исполняется молча и не считается закрытой правкой текста.
 
-### 4. Серия задач объявляется эпиком
+**Следующее движение:** сверенная с разбором договорённость коммитится, и тем же ходом
+заводятся задача, ветка и папка — а вышла из разбора серия, сперва объявляется эпик.
+
+### Состояние `договорённость-записана`: серия задач объявляется эпиком
 
 Разбор кончился одной задачей — шаг пропускается. Вышло несколько, и порядок между ними
 значим — эпик объявляется здесь, до первой из них, и дважды: карточкой в очереди работ с меткой
@@ -134,7 +143,10 @@ Workflow(name: "plan", args: "docs/tasks/_draft-<slug>")
 Лежит замысел вне папки задачи: та умирает с мержем первой же задачи. Каталог для него называет
 компаньон правила — у пакета своего пути нет.
 
-### 5. Задача, ветка, папка
+**Следующее движение:** объявленный эпик коммитится, и тем же ходом берётся первая его
+задача — заведением задачи, ветки и папки.
+
+### Состояние `договорённость-записана`: задача, ветка, папка
 
 ```bash
 npm run task:new -- --title '<Что не так>' --slug <slug> --label documentation --label area:tooling < тело.md
@@ -162,7 +174,19 @@ cp docs/tasks/_template/plan.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/plan.m
 cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/progress.md
 ```
 
-### 6. Шапка замысла
+В ходе работы первой строкой объявляется состояние — с этой минуты его читает гард:
+
+```markdown
+- **Состояние:** `задача-взята`
+```
+
+Пока не объявлено состояние, в котором код правится, гард отбивает правку и называет
+обязательное действие того состояния, которое стоит в строке.
+
+**Следующее движение:** объявив состояние, тот же ход берётся за замысел — начиная с его
+шапки. Заведённая папка ходом не кончается: в ней ещё нет ни одного написанного файла.
+
+### Состояние `задача-взята`: шапка замысла
 
 Её читает гард:
 
@@ -180,6 +204,32 @@ cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/pr
 
 Пустая причина не принимается.
 
+**Следующее движение:** под шапкой пишутся след задачи и этапы, замысел коммитится, и тем же
+ходом начинается первый этап.
+
+### Состояние `замысел-записан`: первый этап начинается тем же ходом
+
+Замысел закоммичен — работа переходит в первый этап сразу, не отдавая хода. Строка состояния
+перезаписывается на `этап-идёт`, и дальше работу ведёт паттерн возвращения.
+
+```markdown
+- **Состояние:** `этап-идёт`
+- **Этап:** 1 из 3 — <название первого этапа из замысла>
+```
+
+Ход на этой границе не кончается. Написанный замысел выглядит законченным куском: этапы
+разложены, файл закоммичен, отчитаться есть чем — и отчёт встаёт ровно на то место, которое
+должна была занять работа. Владелец читает такой отчёт как сделанное, а сделано ничего. Так
+и вышло 21 августа: заход кончился строкой «следующий шаг — такой-то» при заполнении окна около
+двух процентов.
+
+Кончают ход четыре вещи, и они те же, что у остальных состояний: предел заполнения окна, отказ
+гарда, вопрос владельцу и отданная работа, по которой начата следующая. Дочитанный до конца
+паттерн к ним не относится — текст кончился, работа нет.
+
+**Следующее движение:** первый этап делается тем же ходом, а закрытым он объявляется после
+того, как прошла его команда из строки «Чем проверяется».
+
 ## Ловушки
 
 - **Номер не бывает первым.** До конца разбора неизвестно даже, сколько задач из него выйдет:

package/assets/patterns/turn-entry-map.md

@@ -0,0 +1,81 @@
+---
+name: turn-entry-map
+kind: pattern
+rule: turn-entry
+description: Паттерн правила turn-entry. Брать при правке карты хода и хука, который её подаёт, — что в карту входит, чем она отличается от правила, как хук молчит о недостающем и как это проверяется. Не брать для формы самой передачи — это паттерн task-flow-handoff.
+---
+
+# Карта хода и её подача — готовый код
+
+Паттерн правила `turn-entry`. Что при этом должно быть верно — закон
+`docs/constitution/work-conduct.md`.
+
+## Когда брать
+
+- В правило ведения работы добавили состояние — карта отстала.
+- Правится хук входа или порядок, в котором части входа кладутся в контекст.
+- Проверка карты покраснела.
+
+## Что входит в карту, а что нет
+
+Карта отвечает на вопрос «что делать», правило — на вопрос «почему». Признак отбора один: строка,
+которую заход прочитает и после которой сделает следующий шаг, — в карту; строка, которая
+объясняет, откуда требование взялось, — в правило.
+
+| В карту                                        | В правило                                          |
+| ---------------------------------------------- | -------------------------------------------------- |
+| имя состояния и его обязательное действие      | почему это действие обязательно                    |
+| паттерн, который состояние ведёт               | разбор происшествия, из которого оно выросло       |
+| четыре выхода хода и чем каждый подтверждается | что бывает, когда ход кончают иначе                |
+| строка о том, что остальное — продолжение хода | перечень того, чем ход кончать нельзя, с примерами |
+
+Разбор происшествия в карту не переезжает никогда: он объясняет, а объяснение — это правило.
+
+## Подача: сперва передача, потом карта
+
+Порядок не безразличен. Передача говорит, где именно стоит эта работа, карта — что делают в
+таком месте вообще. Прочитанная первой, карта отвечает на вопрос, которого заход ещё не задал.
+
+```bash
+# передача — по имени текущей ветки, не выбором из каталога
+handoff="$ROOT/${RT_HANDOFF_DIR:-.claude/handoff}/$(git branch --show-current).md"
+[ -r "$handoff" ] && { printf 'ПЕРЕДАЧА ПРОШЛОГО ЗАХОДА\n\n'; cat "$handoff"; }
+
+# карта — своим файлом, а не разбором правила
+[ -r "$map" ] && { printf 'КАРТА ХОДА\n\n'; cat "$map"; }
+
+exit 0
+```
+
+Три вещи в этом куске обязательны и легко теряются:
+
+- **`-r`, а не `-f`.** Файл может существовать и не читаться; `-f` тогда пропускает `cat`
+  дальше, и хук печатает заголовок над пустотой.
+- **`exit 0` в конце и никаких других выходов.** Хук входа ничего не отбивает: заход без части
+  контекста лучше, чем отбитый запуск.
+- **Имя файла собирается из ветки.** Выбор «первого попавшегося» в каталоге подаёт чужую
+  передачу, и выглядит она как своя.
+
+## Чем это проверяется
+
+```bash
+node tools/check-turn-map.mjs   # размер, полнота состояний в обе стороны, четыре выхода
+```
+
+Проверка сверяет имена состояний карты с таблицей правила в обе стороны: состояние, заведённое
+правилом и забытое в карте, и состояние, оставшееся в карте после переименования, — оба
+расхождения.
+
+Живая проба хука делается на дереве, где обе части лежат, и повторяется четырежды: обе части,
+без передачи, без карты, без обеих. Последний случай обязан дать пустой вывод и нулевой код —
+хук, промолчавший с ненулевым кодом, читается как отбитый запуск.
+
+## Ловушки
+
+- **Предел размера назначается замером, а не на глаз.** Первое число выбрали «вдвое больше
+  нынешней карты» — и проверка покраснела на собственном тексте в первом же прогоне: карта в
+  кириллице весит вдвое больше, чем кажется по числу строк.
+- **Выход за предел означает деление карты, а не подъём предела.** Поднятый однажды, он
+  поднимается и во второй раз, и карта тихо становится вторым экземпляром правила.
+- **Карта, разобранная из правила на месте, ломается молча.** Правку разметки таблицы не видит
+  ни одна проверка, а карта после неё приходит пустой — и заход об этом не узнает.