@rt-tools/agent-kit 0.16.0 → 0.17.0

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

@@ -117,18 +117,50 @@ npm run check:docs    # пути, названные в текстах, суще
 3. **Вернувшиеся находки принимают одним ходом** — записать и вернуться к прежнему. Разбор,
    отложенный «до удобного момента», не случается вовсе: заход кончается раньше.
 
-**Следующее движение:** пока роль разбирает, тот же ход занят следующей задачей; вернувшиеся
-находки принимаются одним ходом — записать и продолжить прежнее.
+### Записи груза переводятся в «готово» тем же ходом
 
-## Состояние `влито`: находки разбора ложатся в папку задачи и ждут владельца
+Работа, начатая с приехавшего груза, кончается здесь, а не на разборе папки: до слияния правки в
+дереве нет, и отметка утверждала бы то, чего в главной ветке ещё не лежит. Это единственное
+состояние, где слияние уже случилось, а ход о задаче ещё идёт.
 
-Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск — в папку
-задачи, файлом рядом с ходом работы. Пишет его исполнитель: роль файлов не пишет.
+Ключи берутся из описания прошлого — папки задачи на диске к этой минуте нет, — и подставляются
+полными, как их печатает чтение приёма:
 
-Папка задачи умирает со слиянием, а находки должны пережить весь эпик — владелец читает их
-разом, когда эпик кончился. Поэтому при разборе папки файл находок не удаляется вместе
-с остальным, а **переезжает к замыслу эпика**: там его найдут и после того, как ветка въехала.
-Работа вне эпика показывает находки владельцу сразу, тем же ходом.
+```bash
+npm run cargo:mark -- --state fixed \
+    --proposal <полный ключ> --proposal <полный ключ> \
+    --fix '<чем исправлено: статья правила, гард, проверка, правка кода>'
+```
+
+Приём починки один на вызов, поэтому записи едут пачками по тому, чем закрыты, а не всей задачей
+разом. Ответ читается: «переведено 0» означает, что этот разбор не двинул ничего.
+
+**Следующее движение:** пока роль разбирает, тот же ход занят следующей задачей; записи груза
+переводятся в «готово» этим же ходом, вернувшиеся находки принимаются одним ходом — записать и
+продолжить прежнее, а владельцу о них говорится, когда кончился эпик.
+
+## Находки разбора ложатся к замыслу эпика и ждут владельца
+
+Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск. Пишет
+его исполнитель: роль файлов не пишет.
+
+**Пишутся находки сразу в файл рядом с замыслом эпика, а не в папку задачи.** Разбор идёт
+фоном, и когда он кончится, не знает никто; папка задачи к этому времени бывает уже разобрана,
+а ветка влита и снята. Оба срока назначает не исполнитель, поэтому переезд «из папки к замыслу
+эпика» держится на совпадении, которого может и не случиться. Тем же местом пользуется находка,
+замеченная не разбором, а по ходу работы. Работа вне эпика показывает находки владельцу тем же
+ходом.
+
+**Находки, вернувшиеся после того, как ветка ушла, едут веткой следующей задачи.** Пуш в снятую
+ветку её не обновляет, а заводит заново: коммит остаётся вне главной ветки и пропадает вместе
+с ней. Следующая задача к этому времени уже взята — её веткой уборка за предыдущей и едет.
+Эпик кончился и следующей задачи нет — находки уезжают своей задачей.
+
+**Накопительный файл находок делится до дописи, а не после.** Длина смотрится одной командой
+перед первой написанной строкой: раздел задачи занимает десятки строк, и предел длины документа
+он переходит молча. Гейт пуша показывает превышение, когда допись уже закоммичена, — тогда
+деление идёт задним числом, вместе с правкой ссылок на файл. Не влезает — заводится следующая
+часть, и раздел пишется сразу в неё.
 
 **Наружу без слова владельца уезжает только сводка наблюдений.** Она говорит, чем пользовались
 и чем не пользовались ни разу, — это факт, и мнением он не станет. Предложение — другое дело:
@@ -155,9 +187,6 @@ npm run check:docs    # пути, названные в текстах, суще
 котором владелец сказал вслух, уходит наружу в тот же ход: написанное и не отправленное лежит в
 дереве неотличимо от отправленного.
 
-**Следующее движение:** записанные находки работу не держат — следующая задача уже идёт, а
-владельцу о них говорится, когда кончился эпик.
-
 ## Ловушки
 
 - **Папку разбирают до открытия заявки — потом о ней уже никто не вспомнит.** Сверка очереди
@@ -165,8 +194,11 @@ npm run check:docs    # пути, названные в текстах, суще
   следующей задаче, и находка достанется чужому заходу. Держит это гард поставки:
   открытие заявки отбивается, пока папка лежит в ветке.
 - **Разбор папки идёт последним коммитом, после того как гейт пуша прошёл целиком.** Порядок
-  один: мерж главной ветки, все линтеры и проверки зелёные, вливание договорённости, приведение
-  текстов домена, разбор папки — и только потом заявка.
+  один: мерж главной ветки, вливание договорённости, приведение текстов домена, все линтеры и
+  проверки зелёные, разбор папки — и только потом заявка. Дешёвый шаг стоит раньше дорогого:
+  заход, потративший окно на прогон, упирался в порог заполнения на четырёх строках привязки, и
+  дописать их было уже нечем. Второй довод сильнее: прогон, стоящий после вливания, проверяет и
+  само вливание — иначе он смотрит то состояние дерева, которое в главную ветку не поедет.
 - **После разбора замысла на диске нет, и собирать папку заново не надо.** Правку по замечаниям
   разбора и починку красного прогона гард хода работы пропускает по признаку из истории ветки:
   папка, снятая её коммитом, и есть признак отданной работы. Собранная заново папка вернула бы

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

@@ -12,14 +12,22 @@ description: Паттерн правила task-flow. Брать при дове
 
 ## Когда брать
 
-- Этапы замысла закрыты, набор гейта прогнан целиком.
+- Этапы замысла закрыты.
 - `npm run check:specs` перечислил договорённость в разделе «Пора вливать».
+- Спек меряется длиной сразу после вливания: выросший делится тем же коммитом.
 - Тексты домена приводятся к тому, что работа сделала.
+- Набор гейта прогнан целиком — после вливания и приведения текстов, а не до них.
 - Папка задачи разобрана, и заявка открывается черновиком.
 - Прогон на вершине зелёный, и с заявки снимается черновик.
 
 Разбор самой папки сюда не относится — это паттерн `task-flow-archive`. Он стоит между
-приведением текстов и открытием заявки: заявка открывается уже за убранной работой.
+прогоном набора и открытием заявки: заявка открывается уже за убранной работой.
+
+**Прогон стоит после вливания договорённости и приведения текстов, а не перед ними.** Оба этих
+шага стоят минуты, а прогон — окно захода: заход, потративший его на прогон, упирался в порог
+заполнения на четырёх строках привязки, и дописать их было уже нечем. Второй довод сильнее
+первого — прогон, идущий после вливания, проверяет и само вливание; идущий до него, он смотрит
+то состояние дерева, которое в главную ветку не поедет.
 
 ## Состояние `этапы-кончились`: договорённость вливается в спек домена
 
@@ -30,11 +38,19 @@ description: Паттерн правила task-flow. Брать при дове
 npm run check:specs   # раздел «Пора вливать» называет готовые директории
 ```
 
+**Спек меряется длиной тем же ходом.** Вливание — известное движение, растящее спек: одно
+довело его до 572 строк при пределе 500, и узнал об этом исполнитель отказом гарда пуша, то
+есть после коммита. Выросший делится на поддомены здесь же, а не на пуше.
+
 Порядок переезда:
 
 - правила из `proposed/<фича>/spec.md` дописываются в `spec.md` домена, в его разделы;
 - сценарии переезжают в `scenarios.md` домена **с прежними номерами**: на них ссылаются
   заголовки тестов, и пересчёт рвёт сверку;
+- сценарии, у которых работа переписала обещание, правятся на месте: номер прежний, текст
+  новый, заголовок теста правится тем же коммитом. Работа, снимающая приём, переписывает уже
+  записанное обещание чаще, чем заводит новое, а список, перечисляющий одну допись, эту правку
+  не называет вовсе;
 - привязки из `proposed/<фича>/implementation.md` дописываются в `implementation.md` домена
   и проставляются на код, который теперь есть;
 - законы, объявленные фичей в шапке, дописываются в шапку спека домена;
@@ -103,11 +119,60 @@ grep -rn -A3 "Чего из закона здесь нет" <каталог пр
 работа ждёт владельца, а не машину, и заход на этом не кончается: следующая задача берётся тем
 же движением, паттерн `task-flow-resume`.
 
+**Готовность меряется рассказанностью, а не пройденностью.** Перечень того, что сделано к
+открытию, читается как список обязательных проверок, и границы у него не видно. Она есть:
+проверка, которую исполнитель не может пройти по причине вне работы — отбитое разрешение,
+недоступная среда, ключ у человека, — готовность не отменяет. Она попадает в «Не гонялось» и в
+«Оставшийся шаг», названная вместе с причиной; умолчание о ней читается как пройденная.
+
 Состояния на диске уже нет — ход работы уехал вместе с папкой. Это цена того, что уборка стоит
 до заявки: хвост из четырёх шагов — открыть заявку, дождаться прогона, снять черновик, попросить
 влить — держится этим паттерном, а не строкой в файле. Гард признаёт работу отданной по истории
 ветки: папка, снятая её коммитом, и есть признак.
 
+### Раздел об оставшемся шаге пишется в теле заявки, а не дописывается потом
+
+Он стоит там с минуты открытия. Сказанного вслух мало, и одним этим требование не держится:
+реплика живёт до следующей реплики, а решение о слиянии принимается на странице заявки — там
+переписки нет вовсе. Владелец вливает, как только видит зелёное, и заявка, открытая без раздела,
+уезжает в главную ветку раньше, чем раздел успевают дописать: так папка задачи однажды и уехала
+неразобранной, пока шёл прогон. Раздел стоит последним и говорит ровно одно: осталось ли что-то
+до слияния.
+
+```markdown
+## Оставшийся шаг
+
+Папка задачи разобрана коммитом `<sha>` — за работой убрано. Осталось дождаться прогона и снять
+черновик; до этого кнопка слияния заблокирована хостингом.
+```
+
+Черновик снят — раздел переписывается тем же вызовом, которым правится тело:
+
+```markdown
+## Оставшийся шаг
+
+Не осталось: прогон зелёный, черновик снят. Можно вливать.
+```
+
+Заголовок раздела и слова обоих образцов пишутся языком заявки, а не языком паттерна. Образцы
+набраны тем языком, которым написан сам паттерн, и переносятся целиком — порядок мыслей,
+формулировки и заголовок, заголовок последним: он выглядит частью формы, а не частью текста.
+То же верно и для двух сообщений владельцу ниже: они образцы того, **что** сказано, а не того,
+какими словами.
+
+Пустым раздел не оставляется и не удаляется вовсе: отсутствие раздела и «шагов не осталось»
+читаются одинаково, а значат разное. Образец тела заявки целиком — в паттерне заведения коммита
+и заявки, если дерево его разложило.
+
+Держит это гард поставки, а не память пишущего: он читает тело прямо из команды открытия —
+доводом оно передано или файлом — и отбивает вызов вместе с остальным несошедшимся. Образец
+заголовка при этом называет дерево, потому что заголовок пишется языком заявки, а пакет чужих
+слов не знает; не названный, раздел не судится вовсе. Сверка очереди работ тела по-прежнему не
+читает: промах ловится в минуту открытия, то есть там, где он ещё исправим одним вызовом.
+
+Разница между разделом и сказанным вслух одна, и она вся: реплику владелец прочитает, только
+если вернётся в переписку, а раздел он видит там, куда смотрит, нажимая кнопку.
+
 ### Два сообщения владельцу, и между ними — прогон
 
 Оба обязательны, и порядок между ними один. Ни одно не заменяется другим: первое говорит, что
@@ -175,6 +240,12 @@ PR #<номер> готов к слиянию: прогон зелёный, че
 читаются одинаково, а значат разное. Образец тела заявки целиком — в паттерне заведения коммита
 и заявки, если дерево его разложило.
 
+Открытая заявка перечитывается той записью, которая будет её вливать, а не той, что её открыла.
+Ответ хостинга автору говорит лишь, что вызов прошёл: право на открытие и видимость открытого —
+разные вещи, и вторая проверяется только со стороны читателя. Невидимая заявка ничем себя не
+выдаёт — она есть в ответе своему автору, у неё стоят метки, а очередь разбора у владельца просто
+пуста.
+
 Проверить это машиной нечем, и проверки не будет: тело заявки не читает ни одна сверка, а
 хостинг не спрашивает ни о чём, кроме заголовка. Требование держится тем же, чем и слова
 вслух, — тем, кто пишет тело. Разница между ними одна, и она вся: реплику владелец прочитает,
@@ -186,6 +257,11 @@ PR #<номер> готов к слиянию: прогон зелёный, че
 нет, и собирать папку заново не надо: гард хода работы пропускает правку по признаку из истории
 ветки. Что именно чинится, берётся из замечания, а не из замысла.
 
+Главная ветка, влитая ради того, чтобы что-то посмотреть, — такая же правка, как влитая ради
+работы, и уезжает тем же ходом. Конфликт тут ни при чём: он делает промах заметнее, а не создаёт
+его. Слияние, оставшееся в рабочей копии, либо пушится тем же ходом, либо не делается — иначе
+владелец видит прежнее состояние и решает по нему.
+
 **Следующее движение:** прогон зелёный и замечаний нет — черновик снимается, и владельцу
 говорится, что работа готова.
 

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

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

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

@@ -33,6 +33,16 @@ Agent(subagent_type: "Explore", prompt: "<тема просьбы>: что по
 
 Находки складываются в раздел «Что уже есть в дереве» разбора.
 
+Дерево — не единственное место, где может лежать ответ. Решение, принятое прошлым заходом и
+никуда не записанное, живёт только в записи того захода: записи заходов лежат в каталоге заходов
+агента, и поиск по ним словом темы стоит одной команды. Найденное там ответом не остаётся на
+месте — тем же ходом оно переписывается в дерево: в замысел эпика, если связывает задачи, и в
+ход работы, если касается одной.
+
+Разведка, не нашедшая ничего, разрешением спрашивать не становится. Сначала называется, где
+искали, потом добираются места, которых в списке не было: замысел эпика, описание прошлого,
+записи прошлых заходов.
+
 Разведка кончается не ощущением, а выводом команд. До первого вопроса владельцу исполнитель
 знает: как устроен репозиторий (корневая памятка), что лежит в каталоге, о котором пойдёт речь
 (`ls`), и есть ли уже написанное по теме (поиск по документации и правилам). Вопрос называет,
@@ -68,6 +78,17 @@ Agent(subagent_type: "Explore", prompt: "<тема просьбы>: что по
 | Чем будет видно, что задача закрыта          | «работает» признаком не является                         |
 | Есть ли образец, с которого снимается подход | разведка найдёт похожее, а не то                         |
 
+Список шести — набор того, что должно быть закрыто к началу работы, а не набор реплик, которые
+надо произнести. Обязательный вопрос, ответ на который владелец уже дал, отмечается закрытым, а
+не задаётся: ответ ищется в двух местах — в документации и в том, что владелец сказал в этом же
+заходе, включая исходную просьбу. Слово, повторённое в просьбе несколько раз, ответом является.
+Закрытый вопрос отмечается в разборе просьбы вместе с тем, чем он закрыт.
+
+Объём работы основанием для вопроса о границах не бывает. «Это большая работа» и «делать ли её
+целиком» — разные вопросы: первый исполнитель решает сам, второй владелец решает раньше, чем
+работа началась. Вопрос о границах задаётся тогда, когда владелец границ не назвал, — а не
+тогда, когда названные оказались широкими.
+
 Форму вопроса задают настройки владельца: где они требуют меню, спрашивается меню, и тогда к
 каждому вопросу добавляется свободный вариант — у закрытого набора нет строки «вопрос не тот».
 Выбор слова, имени и термина уточняется прозой в любом случае.
@@ -121,6 +142,11 @@ Workflow(name: "plan", args: "docs/tasks/_draft-<slug>")
 «не входит». Находка критика, расходящаяся с ответом владельца, относится владельцу — она не
 исполняется молча и не считается закрытой правкой текста.
 
+Ход на этой границе не кончается. Закрытый разбор выглядит законченным куском: ответы владельца
+лежат на диске, файл закоммичен, отчитаться есть чем — и отчёт встаёт ровно на то место, которое
+должна была занять договорённость. Пишется она тем же ходом, конвейером ролей или рукой
+исполнителя, и разницы между этими двумя случаями для конца хода нет.
+
 **Следующее движение:** сверенная с разбором договорённость коммитится, и тем же ходом
 заводятся задача, ветка и папка — а вышла из разбора серия, сперва объявляется эпик.
 
@@ -155,6 +181,13 @@ Workflow(name: "plan", args: "docs/tasks/_draft-<slug>")
 таблицы, с меткой эпика. Выданные номера возвращаются в ту же таблицу — колонкой или приставкой
 к названию, — и с этой минуты «взять следующую» отвечает номером, а не названием.
 
+Задача, заведённая под эпик, называет его в своём теле: номер карточки эпика и путь к замыслу —
+одной строкой. Замысел называет задачу со своей стороны, и односторонняя привязка выглядит целой
+ровно так же, как двусторонняя — читатель приходит то от линии работ, то от карточки, и вторая
+сторона существует только для одного из них. Держалась она подражанием: пока тело писалось с
+образца соседней задачи того же эпика, строка копировалась вместе с формой, а задача, заведённая
+посреди работы находкой сверки, писалась не с образца.
+
 **Следующее движение:** объявленный эпик коммитится вместе с номерами задач, и тем же ходом
 берётся первая его задача — заведением ветки и папки.
 
@@ -208,6 +241,13 @@ cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/pr
 **Поведение:** меняется
 ```
 
+Дерево, у которого каталога «предложено» нет, называет договорённость самим спеком домена — там
+она пишется прямо в него, и переезжать при закрытии работы нечему:
+
+```markdown
+**Спек:** `docs/specs/bookings/spec.md`
+```
+
 Работа, не задевающая `apps/**` и `libs/**`, договорённости не требует:
 
 ```markdown
@@ -254,7 +294,5 @@ cp docs/tasks/_template/progress.md docs/tasks/<КЛЮЧ>-<номер>-<slug>/pr
 - **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
   привязана, и задача попадает на неё только явным добавлением.
 - **Slug ветки берётся из терминологии договорённости, а не из слов просьбы.** Договорённость
-  пишется раньше ветки и как раз там отказывается от слова владельца: спек завёл своё имя
-  предмету и прямо сказал, каким словом его не называть, — а ветка и папка задачи остались с
-  отвергнутым. Заголовок задачи и PR поправить можно, имя ветки после открытия PR —
-  уже нет.
+  пишется раньше ветки и как раз там отказывается от слова владельца. Заголовок задачи и PR
+  поправить можно, имя ветки после открытия PR — уже нет.

package/assets/pitfalls/agent-kit.md

@@ -42,9 +42,18 @@
   отдельным шагом, отбивается как неиспользуемый ещё до того, как появится строка, которая его
   зовёт, и работа встаёт на половине. Правка делается одним вызовом либо в порядке «сначала
   использование, потом импорт».
-- **Прогонять сценарии гардов можно, ничего не раскладывая.** Обвязка набора принимает каталог
-  гардов переменной, и пакетную редакцию гоняют по сценариям дерева до установки. Заход,
-  потраченный на диагноз по последствиям, стоил ровно этой строки.
+- **Прогонять сценарии гардов можно, ничего не раскладывая, — но только там, где сам пакет живёт
+  исходниками.** Обвязка набора принимает каталог гардов переменной, и пакетную редакцию гоняют
+  по сценариям дерева до установки. Заход, потраченный на диагноз по последствиям, стоил ровно
+  этой строки. В поставке ни обвязки, ни каталога сценариев нет: они живут в репозитории пакета,
+  и дерево-потребитель, поверившее совету, ищет у себя то, чего ему не отгружали.
+
+- **Прогонять сценарии гардов можно, ничего не раскладывая, — там, где эти сценарии есть.**
+  Обвязка набора принимает каталог гардов переменной, и пакетную редакцию гоняют до установки.
+  Живёт она в репозитории самого пакета: в поставку едут ресурсы, строка запуска и библиотека, а
+  каталога сценариев в ней нет вовсе. Дереву-потребителю остаются свои сценарии на свои гарды —
+  искать у себя пакетные значит потратить заход на диагноз по последствиям, ровно тот, от
+  которого совет обещал избавить.
 - **Отбитая правка не всегда про текст гарда.** Гард зовут по пути, и файл без права на
   запуск отвечает отказом доступа — ненулевым кодом, который читается как «правка отбита».
   Набор при этом отбивает подряд всё, включая сборку и тесты, и причины не называет.
@@ -78,3 +87,64 @@
   ровно так же, как с кодом дерева: запись в файл вне репозитория была отбита гардом хода
   работы с требованием замысла, к ней не относящегося. Путь в профиле сначала приводится к
   корню дерева, и всё, что вне корня, признака не получает.
+- **Похожесть текстов ближайшую статью не находит.** Замер показал, что законное соседство двух
+  статей одного правила и законный перенос удачной статьи на соседнее место дают одно и то же
+  число: цитата поэтому ищется точным совпадением, а не мерой похожести.
+- **Отметка об отправке живёт в рабочем дереве, а дерево у каждой ветки своё.** Поставленная в
+  одной ветке, в соседней она не видна, и тот же текст уезжает вторым разом; второй записью он
+  при этом не становится — приём отбирает уже приехавшее по признаку предложения, и его ответ
+  говорит, сколько записей легло и сколько уже лежало. Строка «принято 0, уже лежало 3» означает,
+  что нового не уехало ничего.
+- **Отметка, поставленная только на принятое, объявила бы неотправленным то, что дошло раньше.**
+  Файл остался бы без неё навсегда: принятым он больше не станет никогда, а гард предложений
+  отбивал бы ход у каждого следующего захода. Отправителю разница между принятым и уже лежавшим
+  ничего не меняет — оба исхода значат одно: груз доехал.
+- **Отказ отправки, называющий один лишь ключ конфига, уводит читателя не туда.** Ни адреса, ни
+  токена в конфиге нет и не будет: оба приходят от владельца приёма — адрес словом, токен
+  одноразовым кодом приглашения. Отказ поэтому называет приглашение, а не ключ: ушедший править
+  конфиг ответа там не находит и второй раз спрашивает уже владельца.
+- **Редакция пакета, поднятая без раскладки, запирает дерево целиком.** Красит она не свою
+  ветку, а главную: сверка раскладки стоит в гейте пуша, и на ней отбивается чужая работа, пакета
+  не касающаяся вовсе. Своей веткой такой автор починить это не может — правка лежит в чужой.
+- **Правка разложенного файла без гарда на месте всплывает в чужой ветке.** Знал о ней один
+  `sync --check`, а говорил он на следующей раскладке: отказ приходил тому, кто в этот день
+  правил соседний ресурс, и выглядел поломкой его работы.
+
+## Подъём версии: чем сверять замещённые разделы
+
+Замерено на двух подъёмах подряд: в одном шесть замещённых разделов недосчитались новых
+утверждений, в другом два раздела — одиннадцати статей, и ни одна команда об этом не сказала.
+Прежняя редакция при этом нашлась случайной копией в чужом рабочем дереве: установка стирает её
+без следа, поэтому снимок и стоит первым шагом подъёма.
+
+Сверяются статьи, а не заголовки — заголовок как раз и совпал, этим раздел замещён:
+
+```bash
+sec() { awk -v s="$2" '$0 ~ "^## "s {f=1;next} /^## /{f=0} f' "$1" \
+    | grep '^- \*\*' | sed 's/^- \*\*//;s/\*\*.*//'; }
+comm -13 <(sec "$OLD/<ресурс>" '<заголовок>' | sort) <(sec "$NEW/<ресурс>" '<заголовок>' | sort)
+```
+
+Строка в выводе — статья, которую надстройка проглотила: пакет её дописал, а дерево не увидело.
+Переносится она в надстройку руками.
+
+## Выключенная роль: что бывает с настройкой
+
+- **Настройка, которую не прочитать, роль не выключает.** Не нашлось `jq`, нет настройки, в
+  настройке сломан разбор — гард судит, как судил. Обратный выбор гасил бы слой правил молча, и
+  заметить это было бы нечем.
+- **Ключ, написанный не списком, ловит раскладка, а не гард.** Гарду виден только список имён:
+  строка вместо списка читается им как «роль включена», и роль работает, хотя дерево считает её
+  выключенной. Отказывает на этом разбор настройки — первой же раскладкой, называя ключ.
+- **Выключение живёт в настройке дерева, а не в настройке агента.** Строка, вырезанная из
+  настроек агента руками, теряется на первой же правке того файла, и вернуть роль будет нечем.
+  Здесь оно объявлено в одном месте и видно всякому, кто читает настройку дерева.
+
+## Свойства дерева: две границы
+
+- **`only` сильнее требования.** Ресурс, названный поимённо, ложится и при неотвеченном
+  требовании; перечень раскладки называет это вслух, а отказ по его пустому компаньону зовёт
+  снять ресурс, а не заполнять черновик.
+- **Свойство, которого пакет не объявлял, роняет раскладку** — что в `has` дерева, что в имени
+  ресурса. Объявлены свойства перечнем при пакете, рядом с осями различия.
+

package/assets/pitfalls/doc-style.md

@@ -7,6 +7,11 @@
 
 ## Ловушки
 
+- **Отступление от просьбы называется в том же докладе, где показан результат.** Сделанное не
+  тем способом, о котором просили, отличается от сделанного просимым способом даже при совпавшем
+  ответе, и разницу называет исполнитель — одной строкой «сделал не тем, чем сказано, вот чем и
+  вот почему». Умолчание держится ровно до того, как просьбу приходится повторять, а платит за
+  него доверие ко всему докладу.
 - **Оставшаяся работа не записывается в документ, а заводится задачей.** `docs/BACKLOG.md`
   держит только то, что задачей не бывает: договорённости и решения, которые решено не
   править. Признак — утверждение остаётся, если править его никто не собирается. «Сделать

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

@@ -97,8 +97,57 @@
 Сюда уехали случаи, числа и отвергнутые лекарства, стоявшие прежде при статьях правила. Ни одно
 решение по правке на них не стоит: они нужны тому, кто разбирает промах или спорит с гардом.
 
+- **Отказ на слиянии остаётся вторым рубежом.** Человек вливает, как только видит зелёное, и до
+  второго рубежа дело просто не доходит.
+
+- **Список, в котором всё серое, читается как «работа не сделана».** Черновик и недоделанное
+  выглядят одинаково; находит такие заявки сверка — ночью, в чужой сессии, после закрытого
+  разговора.
+- **Логин рядом со служебным числом не сверяет никто.** Промах в почте изнутри не виден вовсе:
+  коммит выглядит своим, а подписан посторонним.
+
+- **Ключ задач, разошедшийся с формой ветки в профиле.** Они не отказывают, а перестают узнавать
+  номер: проверка, искавшая работу без задачи, пропускает всё подряд.
+- **Сложение у указателя зовут не ради спора, а ради тишины.** Без объявления человека зовут при
+  каждом слиянии — по строке, которая нужна целиком с обеих сторон.
+
+- **Гейт — обещание, что пуш не приедет красным.** Набор без сборки и снимков обещает то, чего не
+  проверяет.
+- **Борда показывает, что сделано и что осталось.** Заявка отвечает на другой вопрос и
+  связывается с карточкой сама — отдельной карточки ей не нужно.
+
+- **Сливаемость выводили из локального вливания.** Между ним и взглядом владельца главная уходит
+  вперёд, и «у меня слилось» о кнопке не говорит ничего. Дерево, чей помощник очереди о поле
+  `mergeable` не говорит вовсе, работает как прежде: поля нет — требования нет.
+- **Личность вызова, открывающего заявку.** Дерево, не назвавшее машинной записи, требования
+  подстановки токена не получает: сверять ответ хостинга не с чем.
+
+- **Ветки, заведённые от главной подряд, роняют друг друга.** Замер по ста шести накопленным
+  веткам одного основания: вливание одной делает расходящимися до двадцати трёх, в среднем семь с
+  половиной; не расходятся ни с кем двенадцать. Считался он `git merge-tree` в памяти — рабочего
+  дерева замер не трогает и веток не двигает.
+
+    ```bash
+    # проба слияния без единой правки в дереве: коммит-слияние заводится в объектной базе
+    tree="$(git merge-tree --write-tree origin/main <ветка> | head -1)"
+    probe="$(git commit-tree "$tree" -p origin/main -p <ветка> -m проба)"
+    git merge-tree --write-tree "$probe" <другая ветка> >/dev/null; echo $?   # 1 — разойдутся
+    ```
+
+    Дерево аргументом сюда не годится: истории у него нет, общее основание не считается, и любая
+    проба отвечает «сойдётся».
+
+- **Расходится не правка, а строка, куда дописали обе стороны.** В том же замере исходник
+  ресурса сливался чисто, а его разложенная копия расходилась первой строкой — той, где стоит
+  контрольная сумма ресурса. Две работы правили разные разделы разных файлов, и всё равно
+  требовали разбора. Отсюда и правило ветвиться чередой: снимать пришлось бы не расхождение, а
+  сам способ хранить копию рядом с исходником.
+
 - **Сборка входит в набор гейта.** Четыре мержа подряд уехали в главную ветку, ломая выкатку:
   ошибка типов в непокрытом коде пережила линт и юниты и всплыла на сборке образа.
+- **Набор, переписанный строками, выглядит полным.** В одном дереве шесть проверок лежали рядом
+  с гоняемыми и не гонялись ни гейтом, ни конвейером: восемь строк из четырнадцати читались как
+  весь набор, и разница была видна только сличением с умолчанием пакета.
 - **Набор гейта не бывает уже набора конвейера.** Дважды подряд правка, прошедшая гейт целиком,
   была отбита конвейером — и оба раза зелёный гейт был прочитан как «локально всё зелено». Отсюда
   и требование отбивать пуш на шаге без строки в наборе, а не печатать предупреждение рядом.
@@ -110,6 +159,12 @@
   в шести ветках за один заход. Обещать по объявлению «конфликтов больше не будет» нельзя: не
   будет ручной работы, а вливать главную в открытые ветки после каждого слияния придётся
   по-прежнему.
+- **Заведённое видно только заводящему.** Шестнадцать задач так были заведены дважды, а заявка
+  названа владельцу номером, которого для него не существовало: ограниченная запись видела своё,
+  а хостинг отвечал остальным «не найдено».
+- **Обойдённый отказ унёс признак ограничения.** Предел запросов у ограниченной записи стоял на
+  нуле — не исчерпан, а не положен вовсе. Отказ обошли вызовом другого рода, обход сработал, и
+  расхождение всплыло через двадцать минут и четыре следа, которые пришлось переписывать.
 - **Личность вызова, открывающего заявку.** Прежде обе стороны — подстановка токена и ответ
   хостинга об авторе — держались статьёй и разбором происшествия, и промах повторился на третий
   день.
@@ -131,3 +186,16 @@
   дали, а запрос разбора на автора хостинг принимает молча и не создаёт.
 - **Ревьюверы спрашиваются вызовом REST.** Под токеном машинной записи выборка клиента падает
   целиком, без токена проходит зелёной — отличить «сошлось» от «спросить было нечем» нечем.
+
+- **Полнота набора гейта судится по именам шагов конвейера.** Проверки, которой нет и в
+  конвейере, там нет тоже: набор, переписанный строками вместо вызова умолчания пакета, теряет
+  ровно те проверки, которые пакет заведёт следующей редакцией. Своя строка вместо умолчания
+  законна там, где она покрывает то же строже либо зовёт названный скрипт.
+- **Черновик, чья ветка везёт папку задачи, означает идущую работу, а не брошенную.** Оба
+  признака нужны вместе: зелёный прогон на вершине без разобранной папки говорит, что работа
+  ещё не отдана. Дерево, не назвавшее машинной записи, этой сверки не получает вовсе.
+- **Метку сливаемости не гасит и объявленное сложение обеих сторон.** Хостинг считает сложение
+  своим приёмом и настроек слияния не читает: пока ветка не вобрала главную и это не уехало на
+  хостинг, заявка стоит конфликтующей при разрешённом на месте расхождении.
+- **Сверки раскладки нет в конвейере, поэтому шага, который она бы закрывала, там тоже нет.**
+  Правка мимо источника в день, когда её делают, не ломает ничего.

package/assets/pitfalls/spec-driven.md

@@ -34,3 +34,19 @@
   его привязка перестают находиться друг по другу. После разрешения гоняется
   `npm run check:specs` — конфликт в спеке кода не задевает, и ни сборка, ни линтеры его не
   увидят.
+
+- **Строку требования к соседнему ресурсу не проверяет ничто, и расхождение видно только
+  счётом.** Правило без неё выглядит целым: разделы на месте, привязки сходятся, сверка
+  полноты зелёная. Требовать её у всех нельзя — правило, которому нечего требовать, её не
+  пишет, — поэтому судит не проверка, а два числа рядом: сколько правил в каталоге и сколько из
+  них требование объявило.
+
+    ```bash
+    ls <каталог правил> | wc -l
+    grep -rl '^\*\*Требует:\*\*' <каталог правил> | wc -l
+    ```
+
+    Расхождение отказом само по себе не бывает. Оно называет, сколько правил прочитать глазами,
+    и число это падает по мере того, как их читают. Счёт при этом грубый: строка, показанная
+    образцом внутри ограды, считается наравне с настоящей — тот, кто учит её писать, попадает
+    в число объявивших.