@rt-tools/agent-kit 0.5.0 → 0.5.2

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

@@ -10,6 +10,8 @@ description: Паттерн правила task-flow. Брать при возв
 Паттерн правила `task-flow`. Что при этом должно быть верно — закон
 `docs/constitution/work-conduct.md`.
 
+**Требует:** `hooks/task-context-load.sh`
+
 ## Когда брать
 
 - Сессия начата на ветке `<КЛЮЧ>-*`, работа в ней уже шла.
@@ -32,7 +34,7 @@ description: Паттерн правила task-flow. Брать при возв
   ней проверяется деревом — сборкой, тестами, чтением файла, — а не вопросом.
 - **Не править замысел.** С ним сверяют результат; пересмотр идёт записью в ходе работы.
 
-## Первое действие захода
+## 6. Возвращение к работе новым заходом
 
 Сверить «Где стоим» с деревом. Запись описывает день, когда её сделали:
 
@@ -44,7 +46,7 @@ git log --oneline origin/main..HEAD
 Разошлось — «Где стоим» правится сразу, до работы: следующий заход поверит записи, а не
 дереву.
 
-## Как ведётся ход работы
+## 7. Этап делается и отмечается в ходе работы
 
 Раздел «Где стоим» **перезаписывается**, а не дописывается — это первое, что читает следующий
 заход, и единственное, что переживает обрезку по объёму:
@@ -57,6 +59,16 @@ git log --oneline origin/main..HEAD
 - **Следующий шаг:** сценарии обоих хуков, затем подключение в настройках
 - **Незакоммиченное:** всё, ветка пока без коммитов
 - **Ждём владельца:** нет
+- **Отчёт:** ещё не открыт
+```
+
+Строка про отчёт обязательна с той минуты, как этапы кончились: между открытием отчёта и
+слиянием проходит день и больше, и заход обрывается там чаще всего. Без неё следующий заход
+читает «этап последний, всё зелено» и об открытом отчёте узнаёт только из истории ветки или у
+владельца — то есть ровно тем пересказом, ради отмены которого всё и заведено:
+
+```markdown
+- **Отчёт:** #1396, ждёт разбора · отвечено 3 замечания из 5 · не сделано: разбор папки задачи
 ```
 
 Решение, принятое по ходу, — вместе с причиной и с тем, что было альтернативой:

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

@@ -17,6 +17,10 @@ description: Паттерн правила task-flow. Брать в начале
 
 ## Порядок
 
+Шаги ниже — начало сплошного счёта: номер шага один на весь путь работы и в следующем паттерне
+не начинается заново. Весь список — в правиле `task-flow`; он же показывается владельцу в начале
+работы, чтобы после шести вопросов было видно, что впереди.
+
 ### 1. Разведка — до первого вопроса
 
 Вопрос, ответ на который лежит в коде, владельцу не задаётся: он обесценивает и остальные.
@@ -29,6 +33,13 @@ Agent(subagent_type: "Explore", prompt: "<тема просьбы>: что по
 
 Находки складываются в раздел «Что уже есть в дереве» разбора.
 
+Разведка кончается не ощущением, а выводом команд. До первого вопроса владельцу исполнитель
+знает: как устроен репозиторий (корневая памятка), что лежит в каталоге, о котором пойдёт речь
+(`ls`), и есть ли уже написанное по теме (поиск по документации и правилам). Вопрос называет,
+где искали: «в таком-то месте не нашёл» — проверяемо, «не знаю» — нет. Без списка того, что
+считается сделанным, разведка исполняется как настроение: прочитанный переданный текст сходит
+за неё, и по текущему дереву не запускается ни одной команды.
+
 ### 2. Разбор с владельцем
 
 Ведёт главный агент: субагент до владельца не достучится. Команда — `/grill-me`, один вопрос
@@ -49,6 +60,24 @@ Agent(subagent_type: "Explore", prompt: "<тема просьбы>: что по
 каждому вопросу добавляется свободный вариант — у закрытого набора нет строки «вопрос не тот».
 Выбор слова, имени и термина уточняется прозой в любом случае.
 
+**Рамка переданного текста на текущее дерево не переносится.** Передача захода, файл
+предложений и спек описывают то дерево, в котором писались. Про текущее знает только текущее:
+прежде чем принять из такого текста утверждение о раскладке, оно проверяется командой здесь.
+Подтверждение при этом находится само — признаки дерева, только ставящего пакет, стоят и у
+дерева, которое пакет и пишет, и ставит.
+
+Сообщение, которым исполнитель останавливается, начинается с того, чего он ждёт:
+
+```
+Стою на выборе <что решается>. Без ответа <что будет: пойду допущением таким-то / работа стоит>.
+<Вопрос>
+```
+
+Замеры, находки ролей и список решений к этому моменту уже записаны в ход работы, и в
+сообщении владельцу они лишние. Отчёт, в конце которого стоит вопрос, выглядит добросовестно
+ровно настолько, насколько надёжно вопрос в нём тонет: владелец трижды переспрашивал, почему
+работа стоит, и каждый круг стоил захода обоим.
+
 Ответы пишутся в `docs/tasks/_draft-<slug>/grill.md` — папка ещё черновик, номера нет.
 
 ```bash
@@ -86,10 +115,19 @@ npm run task:move -- <номер> in-progress
 Ветка заводится вторым вызовом: составную «завести и сразу коммитить» гард главной ветки
 отклоняет целиком.
 
-Остальные два файла — с образца:
+Номер уже выдан — черновика нет и не заводится: папка задачи открывается сразу под именем
+ветки, а разбор пишется в неё же. Так начинается половина работ: номер приходит прошлым
+заходом, замеченным дефектом или соседней задачей, и шаг с черновиком в этом случае неисполним
+целиком — переименовывать нечего, `task:new` звать незачем. Ловушка «номер не бывает первым»
+сюда не относится: она про то, что задачу не заводят до разбора, а не про то, что с уже
+заведённой нельзя работать.
+
+Остальные два файла пишутся, а не кладутся образцом впрок: пустой `plan.md` на диске
+неотличим от замысла, у которого нет этапов, — а следующий заход читает папку задачи первым
+делом и доверяет ей. Образец открывается тем же движением, которым заполняется:
 
 ```bash
-cp docs/tasks/_template/plan.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/plan.md
+cp docs/tasks/_template/plan.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/plan.md      # и сразу пишется
 cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/progress.md
 ```
 

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

@@ -44,6 +44,10 @@ description: Правило под «Закон о поставке» для д
   `az repos pr create` с такой ветки: локально она законна, но правка из неё — это выкатка, за
   которой в очереди работ ничего не стоит. Заводится рабочий элемент, и работа переносится в
   ветку с его номером.
+- **Главная ветка влита в ветку рабочего элемента до открытия PR.** Гард поставки отбивает
+  открытие, пока вершина главной ветки не стала предком текущей, и называет расхождение числом
+  коммитов. PR с разошедшейся ветки показывает ревьюверу свою правку вперемешку с чужой, а всё,
+  что автор проверил до публикации, он проверил от основания, которого в главной ветке уже нет.
 - **Номер ветки и номер в заголовке PR сверяются на месте, а состояние — по доске.** Формат
   читается из текста команды и работает без сети; существование рабочего элемента, его
   состояние, исполнитель и то, что он ещё открыт, — только когда есть чем спросить. Нет сети
@@ -107,6 +111,12 @@ description: Правило под «Закон о поставке» для д
 работу вместо промаха. Держится это памятью и подсказкой, которую печатает команда заведения
 задачи. Отставшее состояние находит сверка очереди — но уже после того, как PR открыт.
 
+Свежесть самой вершины главной ветки гард не проверяет: он судит по тому, что лежит в дереве, и
+вершину недельной давности от сегодняшней не отличает. Сетевой вызов сюда не заводится по той же
+причине, что и выше, — он падал бы вместе со связью. Поэтому гард ловит ветку, отставшую
+заведомо, а `git fetch` перед вливанием стоит первым пунктом чеклиста и держится тем же, чем
+держатся остальные его пункты.
+
 ## Паттерны
 
 - `git-workflow-commit` — рабочий элемент, ветка, коммит, пуш и PR от учётной записи машинной
@@ -114,3 +124,32 @@ description: Правило под «Закон о поставке» для д
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится вторым рабочим элементом, здесь нет: делится то, что придётся откатывать порознь.
+  Сплошная правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать
+  два рабочих элемента, закрывать два PR и переносить коммиты по одному с двумя конфликтами.
+  Одна из трёх не дала коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей
+  под ветку тоже.
+- **Рабочий элемент заводится командой, а не вызовами подряд.** Доска показывает элементы своей
+  области и итерации, и заведённый мимо них в очереди работ не виден: со стороны это выглядит
+  так же, как незаведённый. Команда заведения ставит все поля разом — род, состояние,
+  исполнителя, область и итерацию, — и печатает готовую строку заведения ветки. Замеченный по
+  ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

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

@@ -44,6 +44,10 @@ description: Правило под «Закон о поставке» для д
 - **Ветка без номера задачи PR не открывает.** Гард поставки отбивает `gh pr create` с такой
   ветки: локально она законна, но правка из неё — это выкатка, за которой в очереди работ
   ничего не стоит. Заводится задача, и работа переносится в ветку с её номером.
+- **Главная ветка влита в ветку задачи до открытия PR.** Гард поставки отбивает открытие, пока
+  вершина главной ветки не стала предком текущей, и называет расхождение числом коммитов. PR с
+  разошедшейся ветки показывает ревьюверу свою правку вперемешку с чужой, а всё, что автор
+  проверил до публикации, он проверил от основания, которого в главной ветке уже нет.
 - **Ключ задач задаётся один раз, и все три формы имени выводятся из него.** Заголовок задачи,
   имя ветки и заголовок отчёта строит один и тот же ключ: команда заведения задачи собирает по
   нему заголовок, гард поставки достаёт по нему номер из имени ветки, сверка очереди — из
@@ -115,9 +119,43 @@ description: Правило под «Закон о поставке» для д
 работу вместо промаха. Держится это памятью и подсказкой, которую печатает команда заведения
 задачи. Отставшую колонку находит сверка очереди — но уже после того, как PR открыт.
 
+Свежесть самой вершины главной ветки гард не проверяет: он судит по тому, что лежит в дереве, и
+вершину недельной давности от сегодняшней не отличает. Сетевой вызов сюда не заводится по той же
+причине, что и выше, — он падал бы вместе со связью. Поэтому гард ловит ветку, отставшую
+заведомо, а `git fetch` перед вливанием стоит первым пунктом чеклиста и держится тем же, чем
+держатся остальные его пункты.
+
 ## Паттерны
 
 - `git-workflow-commit` — задача, ветка, коммит, пуш и PR от учётной записи машинной работы.
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
+  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
+  закрывать два PR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
+  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
+- **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
+  привязана, и задача попадает на неё только явным добавлением: две задачи так и простояли вне
+  очереди работ, потому что шаг переписывали руками. Команда заведения делает все четыре — issue,
+  номер в его заголовке, добавление на борду, начальную колонку, — и печатает готовую строку
+  заведения ветки. Замеченный по ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

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

@@ -43,6 +43,10 @@ description: Правило под «Закон о поставке» для д
 - **Ветка без номера задачи MR не открывает.** Гард поставки отбивает `glab mr create` с такой
   ветки: локально она законна, но правка из неё — это выкатка, за которой в очереди работ
   ничего не стоит. Заводится задача, и работа переносится в ветку с её номером.
+- **Главная ветка влита в ветку задачи до открытия MR.** Гард поставки отбивает открытие, пока
+  вершина главной ветки не стала предком текущей, и называет расхождение числом коммитов. MR с
+  разошедшейся ветки показывает ревьюверу свою правку вперемешку с чужой, а всё, что автор
+  проверил до публикации, он проверил от основания, которого в главной ветке уже нет.
 - **Номер ветки и номер в заголовке MR сверяются на месте, а состояние задачи — по доске.**
   Формат читается из текста команды и работает без сети; существование задачи, её метка
   списка, исполнитель и то, что она ещё открыта, — только когда есть чем спросить. Нет сети
@@ -105,9 +109,43 @@ description: Правило под «Закон о поставке» для д
 работу вместо промаха. Держится это памятью и подсказкой, которую печатает команда заведения
 задачи. Отставший список находит сверка очереди — но уже после того, как MR открыт.
 
+Свежесть самой вершины главной ветки гард не проверяет: он судит по тому, что лежит в дереве, и
+вершину недельной давности от сегодняшней не отличает. Сетевой вызов сюда не заводится по той же
+причине, что и выше, — он падал бы вместе со связью. Поэтому гард ловит ветку, отставшую
+заведомо, а `git fetch` перед вливанием стоит первым пунктом чеклиста и держится тем же, чем
+держатся остальные его пункты.
+
 ## Паттерны
 
 - `git-workflow-commit` — задача, ветка, коммит, пуш и MR от учётной записи машинной работы.
 - `git-workflow-merge` — главная ветка влита в ветку задачи, конфликт разобран.
 - `git-workflow-migration` — правка схемы хранилища и её миграций.
 - `git-workflow-restart` — ручной перезапуск прода.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
+  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
+  закрывать два MR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
+  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
+- **Задача заводится командой, а не вызовами подряд.** Доска показывает те issue, чью метку
+  знает, и задача без метки списка в очереди работ не видна: со стороны это выглядит так же, как
+  незаведённая. Команда заведения ставит всё разом — issue, номер в его заголовке, метку списка,
+  исполнителя, — и печатает готовую строку заведения ветки. Замеченный по ходу дефект проходит
+  тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор MR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: MR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — отчёт вышел от владельца.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

package/assets/rules/spec-driven.md

@@ -73,6 +73,14 @@ description: Правило под «Закон о документации пр
   внутри спека означает, что предмет описан дважды; занятый чужим — что по номеру не видно,
   чей это сценарий. Договорённость о продукте — исключение: она нумеруется вместе со спеком, в
   который вольётся, и занятым префикс от неё не становится.
+- **Номер сценария выдаётся один раз и повторно не используется.** Новый сценарий берёт
+  следующий свободный номер, а не вставляется в середину и не занимает номер удалённого: на
+  месте удалённого номер так и остаётся пустым. Номер — единственное, чем сценарий связан с
+  тестом, и отданный второй раз он оставляет старую ссылку правильной на вид и ведущей не туда.
+  Пересчитать номера подряд особенно дёшево на вид: тесты зелёные и до, и после.
+- **Сценарий и заголовок его теста правятся одним изменением.** Изменилось обещание — номер тот
+  же, а заголовок теста правится тем же коммитом; удалён сценарий — удаляется и тест.
+  Разъехавшись, они оставляют прогон зелёным, хотя проверяет он уже не то.
 - **Поддомен спрашивается наравне с доменом.** Те же обязательные разделы, тот же компаньон
   рядом, та же связь сценариев с тестами. Домен, у которого половина поддоменов описана, а
   половина заведена пустыми каталогами, зелёным не бывает.
@@ -95,6 +103,12 @@ description: Правило под «Закон о документации пр
 - **Спек объявляет законы, которые применяет, и связь сверяется в обе стороны.** Закон,
   названный в тексте спека, обязан стоять в шапке: иначе по закону не узнать, какие домены
   на нём стоят.
+- **Переносимый текст говорит о соседнем ресурсе условно и называет его по имени.** Что
+  разложено в дереве, а что нет, знает список раскладки, а не текст ресурса. Сказанное
+  безусловно — «правку кода до этого отбивает гард» — приходит в контекст каждой сессии и врёт
+  про дерево, где того гарда не разложили; поправить это дерево не может ничем, если у ресурса
+  нет надстройки. Требование ресурса к ресурсу при этом объявляется строкой в шапке, а не
+  выводится из такой фразы.
 
 ## Чего из закона здесь нет