@rt-tools/agent-kit 0.11.0 → 0.12.0

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

@@ -2,7 +2,7 @@
 name: task-flow-close
 kind: pattern
 rule: task-flow
-description: Паттерн правила task-flow. Брать при закрытии работы — вливание договорённости в спек домена последним коммитом PR, разбор папки задачи, переезд в архив, сверка очереди работ. Не брать для хода работы — это паттерн task-flow-resume.
+description: Паттерн правила task-flow. Брать при доведении работы до готовности — снятие черновика, вливание договорённости в спек домена последним коммитом PR, приведение текстов домена к сделанному. Не брать для разбора папки задачи и разбора работы правилами — это паттерн task-flow-archive; не брать для хода работы — это паттерн task-flow-resume.
 ---
 
 # Закрытие работы
@@ -14,6 +14,7 @@ description: Паттерн правила task-flow. Брать при закр
 
 - Этапы замысла закрыты, проверки зелёные, с PR снимается черновик.
 - `npm run check:specs` перечислил договорённость в разделе «Пора вливать».
+- Тексты домена приводятся к тому, что работа сделала.
 
 Само открытие PR сюда не относится: он открывается черновиком тем ходом, которым правка
 кода отдаётся владельцу, — то есть до этого паттерна и, как правило, задолго до него. Здесь
@@ -176,163 +177,13 @@ grep -rn -A3 "Чего из закона здесь нет" <каталог пр
 договорённость, только про это приложение.
 
 Что сделали на этом шаге, пишется в тело PR: что перечитали, что изменили, а если ничего
-не изменили — почему. Форма раздела — паттерн `git-workflow-commit`.
+не изменили — почему. Форма раздела — паттерн `git-workflow-pr`.
 
 **Следующее движение:** приведённые тексты коммитятся, и тем же ходом разбирается папка
 задачи — последним коммитом ветки.
 
-## Состояние `разбор-кончился`: папка задачи разбирается
-
-Разбор идёт по трём исходам, а не по двум.
-
-**Первым отбирается действующее требование.** Всё, что останется верным и завтра, становится
-статьёй закона, пунктом правила или разделом паттерна — по тому, о чём оно говорит. Признак
-отбора один и записан здесь заранее: перестанет ли текст быть верным, если завтра всё
-переделать. Перестанет — это рассказ о состоявшемся; не перестанет — требование, и место ему в
-слое правил. Закон при этом в ветке не правится — его статья приносится владельцу текстом.
-
-**Вторым отбирается рассказ о состоявшемся переезде.** Он уезжает в описание прошлого и
-называет для каждого перенесённого решения, куда оно ушло: иначе решение, ставшее правилом, и
-решение, потерянное при переносе, выглядят одинаково — записью, на которую никто не ссылается.
-
-**Третьим удаляется остальное.**
-
-Порядок именно такой: начав с переезда, исполнитель увозит вместе с ним и действующее — под
-конец работы это дешевле, чем разбирать.
-
-Целиком в архив не переносится: `docs/archive/` — место для записей о состоявшемся, которые
-кто-то читает, а не свалка ходов работы. Таблица ниже говорит о том, что осталось после
-первого отбора.
-
-| Файл            | Куда                                                                                                               |
-| --------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `grill.md`      | в `docs/archive/` — ответы владельца невосстановимы, и это единственная запись о том, почему задача поставлена так |
-| `progress.md`   | в `docs/archive/`, если в нём есть решения по ходу с причинами; иначе удаляется                                    |
-| `plan.md`       | удаляется — после выкатки на его вопрос отвечает код, а на «как работает» отвечает спек домена                     |
-| находки разбора | переезжают к замыслу эпика — их читает владелец, когда эпик кончится; работа вне эпика показывает их сразу         |
-
-Уезжающее складывается одним файлом с говорящим именем, а не папкой из трёх:
-
-```bash
-cat docs/tasks/<КЛЮЧ>-<номер>-<slug>/grill.md > docs/archive/<ЧТО_РЕШАЛИ>.md
-rm -r docs/tasks/<КЛЮЧ>-<номер>-<slug>
-```
-
-Разбор идёт в том же PR, что и работа: папка, оставленная до мержа, попадает в главную
-ветку и читается там как текущая.
-
-### Работа, разбирающая чужую папку, разбирает две
-
-Своя папка у такой работы есть — она заводится наравне со всеми, исключения из этого нет. Обе
-снимаются последним коммитом, и порядок между ними один: сперва чужая, потом своя. Начав со
-своей, исполнитель теряет замысел на диске, а он ещё нужен — гард отбивает правку без него, а
-правка по замечаниям разбора идёт в ту же ветку.
-
-```bash
-cat docs/tasks/<чужая>/grill.md > docs/archive/<ЧТО_РЕШАЛИ_ТАМ>.md
-rm -r docs/tasks/<чужая>
-cat docs/tasks/<своя>/grill.md > docs/archive/<ЧТО_РЕШАЛИ_ЗДЕСЬ>.md
-rm -r docs/tasks/<своя>
-```
-
-Две записи в архиве, а не одна: работы разные, и решения в них разные. Сверка очереди работ
-после этого не называет ни одной папки — этим и проверяется, что разобраны обе.
-
-**Следующее движение:** разобранная папка уезжает в ветку тем же коммитом, и следом за ним
-сверяется очередь работ.
-
-## Состояние `папка-разобрана`: сверка очереди работ
-
-```bash
-npm run check:board   # папка закрытой задачи среди текущих, брошенные черновики
-npm run check:specs   # договорённость влита, привязки на месте
-npm run check:docs    # пути, названные в текстах, существуют
-```
-
-**Следующее движение:** расхождения, названные сверками, чинятся тем же ходом; чинить нечего —
-тот же ход снимает черновик и просит владельца влить, называя номер.
-
-## Состояние `влито`: работа разбирается правилами — фоном, следом за PR
-
-Шаг о слое правил, а не о продукте: что за эту работу грузилось, что помогло, чего не хватило и
-где текст правила разошёлся с деревом. Знает это только тот заход, который работу вёл, — через
-сутки не знает никто.
-
-Ведёт разбор роль разбора закрытой задачи, если дерево её разложило; не разложившее ведёт его
-само, теми же вопросами. Файлов роль не правит — приносит готовые формулировки, а вставлять их
-решает владелец.
-
-**Запускается разбор в фоне, сразу за открытием PR, и ход на нём не кончается.** Роль ничего не
-спрашивает, пока работает, и быстрее от ожидания не идёт: следующая задача берётся тем же ходом,
-которым запущен разбор.
-
-Порядок один и переставлять его нельзя:
-
-1. **Сводка собирается до запуска** — пока задача ещё в голове. Что делали, что пошло не так,
-   что грузилось и что каждое правило дало, на какие грабли окружения наткнулись. Собранная
-   через две задачи, она пересказывает историю ветки вместо того, что было на самом деле.
-2. **Роль уходит в фон** — инструментом запуска роли, с путём к списку загруженного и сводкой
-   целиком. Ход продолжается следующей задачей.
-3. **Вернувшиеся находки принимают одним ходом** — записать и вернуться к прежнему. Разбор,
-   отложенный «до удобного момента», не случается вовсе: заход кончается раньше.
-
-**Следующее движение:** пока роль разбирает, тот же ход занят следующей задачей; вернувшиеся
-находки принимаются одним ходом — записать и продолжить прежнее.
-
-## Состояние `влито`: находки разбора ложатся в папку задачи и ждут владельца
-
-Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск — в папку
-задачи, файлом рядом с ходом работы. Пишет его исполнитель: роль файлов не пишет.
-
-Папка задачи умирает со слиянием, а находки должны пережить весь эпик — владелец читает их
-разом, когда эпик кончился. Поэтому при разборе папки файл находок не удаляется вместе
-с остальным, а **переезжает к замыслу эпика**: там его найдут и после того, как ветка въехала.
-Работа вне эпика показывает находки владельцу сразу, тем же ходом.
-
-**Наружу без слова владельца уезжает только сводка наблюдений.** Она говорит, чем пользовались
-и чем не пользовались ни разу, — это факт, и мнением он не станет. Предложение — другое дело:
-это заготовка правки чужого дерева, и часть заготовок отпадает при первом же чтении. Уехавшая
-без разбора, она становится работой того, кто её не заказывал.
-
-Порядок такой: находки копятся у замысла эпика → эпик кончился → владелец читает их разом и
-говорит, что из них верно → названное им оформляется предложением и уезжает. Чем отправляют —
-скил слоя правил, если дерево его разложило.
-
-У каждой находки называется адрес, и адресов три:
-
-| Куда                       | Что туда идёт                                                            |
-| -------------------------- | ------------------------------------------------------------------------ |
-| слой правил — предложением | то, что верно любому дереву этого класса: статья, пункт правила, паттерн |
-| имена этого дерева         | то, что верно здесь: компаньон правила, профиль, карта гейта             |
-| надстройка над разложенным | то, что здесь звучит иначе, чем в пакете                                 |
-
-Без адреса правка ложится туда, где её видит автор, — то есть в своё дерево, — и общее оседает
-в одном месте, оставаясь неизвестным всем остальным.
-
-**Разбор без правки закрытым не считается.** Из него выходит либо правка слоя правил, либо
-предложение наружу; не вышло ни того ни другого — это жалоба, и она повторится. Предложение, о
-котором владелец сказал вслух, уходит наружу в тот же ход: написанное и не отправленное лежит в
-дереве неотличимо от отправленного.
-
-**Следующее движение:** записанные находки работу не держат — следующая задача уже идёт, а
-владельцу о них говорится, когда кончился эпик.
-
 ## Ловушки
 
-- **Папку разбирают до слияния — потом о ней уже никто не вспомнит.** Сверка очереди считает
-  задачу закрытой по слиянию: до него папка среди текущих законна, а после за неё никто не
-  отвечает — работа перешла к следующей задаче, и находка достанется чужому заходу. Три раза
-  подряд папка закрытой задачи так и уехала в главную ветку, в последний раз их набралось
-  пять. Теперь это держит гард поставки: слияние отбивается, пока папка лежит в ветке.
-- **Разбирают последним коммитом, а не перед открытием PR.** Пока идёт ревью, замысел
-  нужен на диске: без него правку по замечаниям не пропустит гард хода работы. Порядок такой:
-  правки по ревью, потом разбор папки, потом слияние.
-- **Разбор папки идёт последним, после того как гейт пуша прошёл целиком.** Гард хода работы
-  не пускает правку кода приложения без замысла на диске, а после разбора замысла нет: чужое
-  замечание линтера, приехавшее мержем из главной ветки, чинить уже нечем, и гейт пуша стоит.
-  Порядок один: мерж главной ветки, все линтеры и проверки зелёные, вливание договорённости,
-  приведение текстов домена, разбор папки. Понадобилась правка кода после разбора — замысел
-  восстанавливается на диске на время правки, и разбор повторяется тем же коммитом.
 - **Тексты правятся до разбора папки.** Список того, что перечитывать, лежит в замысле, а
   разбор папки его удаляет. После разбора остаётся только память о том, что задевали.
 - **Утверждение правила снимается вместе со строкой привязки.** Связь идёт по тексту
@@ -343,10 +194,6 @@ npm run check:docs    # пути, названные в текстах, суще
   нет вовсе, и по слову из своей темы эта строка находилась — а неправда была в другом.
 - **Сказать «сверено», не открыв файл, нельзя.** Правило читается целиком. Устаревшее
   утверждение стоит в списке среди верных и ничем от них не отличается.
-- **Если папку просто удалить, первым пропадёт `grill.md`.** Удалить проще, чем разобрать, а
-  слова владельца записаны только там, и восстановить их неоткуда. Поэтому гард требует, чтобы
-  ветка добавила запись в архив. Что именно перенесли, он не проверяет — это смотрит владелец
-  на ревью.
 - **Вливание после мержа не делается.** В главной ветке тогда лежит раздел «предложено, но не
   выкачено» с тем, что работает месяц, — беззвучная ложь, тем убедительнее, чем старше.
 - **Номера сценариев при вливании не пересчитываются.** Идентификатор — ключ связи с тестами;
@@ -356,22 +203,5 @@ npm run check:docs    # пути, названные в текстах, суще
   стоявшее другими словами, а строка «этого раздела ещё нет» становится ложью ровно той
   работой, которая её вливает. Сверка спеков в этот раздел не смотрит вовсе. Снимается
   дословный повтор и то, что работа сделала входящим.
-- **Шаги закрытия с владельцем не согласуются — они перечислены здесь.** Разбор работы
-  правилами входит в закрытие так же, как вливание договорённости и разбор папки; владелец
-  решает не то, запускать ли его, а что делать с находками. Ход, кончившийся таким вопросом,
-  отбивает гард разговора: за ход правила не читались, а ответ стоит в них. Спрашивается только
-  то, чего в правилах нет.
-- **Блок готового кода в паттерне стареет от чужой правки.** Он не привязан ни к чему: сверка
-  спеков читает утверждения правила, а пример под ними не читает вовсе. Два поля, ставших
-  обязательными в чужой работе, сделали пример в соседнем паттерне несобираемым — сам он при
-  этом не изменился ни на знак и в след задачи не попал, потому что ни одного слова той работы
-  в нём нет. Паттерн находится по имени правленого символа, а не по теме работы.
 - **Правило без привязки в спек домена не въезжает.** Кода, который его исполняет, нет —
   значит это намерение, и место ему в открытых вопросах домена, а не в правилах.
-- **Замысел эпика правят только там, где вписывают «чем кончился».** Границы эпика и
-  порядок задач в нём при этом остаются прежними, а работа их уже нарушила: задача, решившая
-  читать спеки, оставила над собой границу «спеки — вторая очередь», и следующий исполнитель
-  прочитает её как действующую. Границы эпика перечитываются целиком тем же заходом, что и
-  итог работы.
-- **Архив не обновляется после выкатки.** Уехавшее туда описывает день переезда, и правится
-  оно только вместе с признанием, что описывало неверно.

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

@@ -1,13 +1,13 @@
 ---
 name: task-flow-handoff
 kind: pattern
-rule: task-flow
-description: Паттерн правила task-flow. Брать, когда заход упирается в заполнение окна — выбор точки остановки, запись хода работы, форма передачи и что владелец с ней делает. Не брать для возвращения к работе новым заходом — это паттерн task-flow-resume.
+rule: turn-conduct
+description: Паттерн правила turn-conduct. Брать, когда заход упирается в заполнение окна — выбор точки остановки, запись хода работы, форма передачи и что владелец с ней делает. Не брать для возвращения к работе новым заходом — это паттерн task-flow-resume.
 ---
 
 # Закрытие захода по заполнению окна
 
-Паттерн правила `task-flow`. Что при этом должно быть верно — закон
+Паттерн правила `turn-conduct`. Что при этом должно быть верно — закон
 `docs/constitution/work-conduct.md`.
 
 ## Когда брать
@@ -55,7 +55,7 @@ description: Паттерн правила task-flow. Брать, когда з
 ### Коммит
 
 Проверенное коммитится сразу, а не копится до конца задачи. Работа кончена — открывается PR:
-паттерн `git-workflow-commit`.
+паттерн `git-workflow-pr`.
 
 ### Передача
 

package/assets/pitfalls/doc-style.md

@@ -0,0 +1,80 @@
+# Тексты проекта — холодная часть
+
+Ловушки: грабли, на которые уже наступали. Грузится не вместе с правилом, а по
+требованию — при обычном решении она не нужна.
+
+Правило — `doc-style`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Оставшаяся работа не записывается в документ, а заводится задачей.** `docs/BACKLOG.md`
+  держит только то, что задачей не бывает: договорённости и решения, которые решено не
+  править. Признак — утверждение остаётся, если править его никто не собирается. «Сделать
+  потом» в плане, README или спеке — второй список работ: он расходится с бордой молча, а
+  разбирать его потом дороже, чем завести задачу сразу. Из 1411 строк документа действующими
+  оказались 71, и на разбор остальных ушла отдельная задача. Как разбирать накопившееся —
+  паттерн `doc-style-sweep`.
+- **Словарь действует и на разговор с владельцем, не только на файлы.** Он приходит в контекст
+  на запуске сессии, поэтому «не читал» основанием не бывает. Слово из левой колонки «Так не
+  пишем» всплывало именно в ответах: в дереве его уже вычистили, а в PR о сделанном оно
+  оставалось, и владелец читал ровно то слово, от которого отказались.
+- **Термин берётся из `docs/GLOSSARY.md`, а не придумывается на месте.** Слова, которого там
+  нет, у читателя нет тоже: «журнал приложения» простоял в спеке почты, пока владелец не
+  спросил, что это, — оказалось, логи бэкенда, а слово «журнал» здесь уже занято журналом
+  событий. Новое слово либо заводится в словаре вместе с правкой, либо заменяется тем, что
+  уже есть.
+- **Проход по словарю глазами слово не находит.** «Формулировки приведены к словарю» означает
+  ровно те строки, которые в тот момент читали: «спека» пережила такой проход и осталась в
+  соседней строке того же файла. Слово из левой колонки таблицы «Так не пишем» вычищается
+  грепом по всему дереву, а не вычиткой. Форма задаётся точно: «спек» — документ — склоняется
+  в «спека» и «спеки» тоже, и совпадений по корню законных больше, чем нарушений; ищутся
+  сочетания («спеки на … нет», «спека проверяет»), а не корень.
+- **Снятое имя вычищается одним грепом по всему дереву:** правила, их зеркала в скилах,
+  документы и комментарии. Описание того, чего в коде уже нет, читается как действующее
+  указание.
+- **У снятого слова второе значение возвращается после сплошной замены, а не обходится до
+  неё.** Слово снимают ровно потому, что оно стояло над двумя вещами, и второе значение при
+  этом остаётся законным. Отобрать его заранее нечем: какое из двух значений в строке, видно
+  только по соседнему тексту, а строк бывают сотни. Порядок обратный — сплошная замена, затем
+  сплошной просмотр самой правки, и найденное второе значение возвращается поимённо. Из 353
+  замен так вернулись шесть, и две первые были поломкой: сверка печатала новое имя дважды
+  подряд, а комментарий обещал «поломку вместо PR о том, что долгов нет». Просматривается
+  правка, а не дерево после неё: в дереве обе стороны выглядят одинаково верными.
+- **Поиск по дереву не покрывает того, что уже уехало наружу.** Заголовок задачи и её тело,
+  заголовок PR и его тело, заголовки коммитов лежат вне файлов, и проверки текстов их не
+  читают вовсе. Вычистив слово в дереве, обходят те же места в очереди работ и в истории:
+
+    ```bash
+    <клиент хостинга> api "<путь к PR>" --jq '.title, .body' | grep -i '<слово>'
+    <клиент хостинга> api "<путь к задаче>" --jq '.title, .body' | grep -i '<слово>'
+    git log --format='%s%n%b' <база>..HEAD | grep -i '<слово>'
+    ```
+
+    Заголовок PR правится вызовом хостинга, заголовок коммита — только переписыванием ветки,
+    поэтому его проверяют до пуша. Выдуманное слово было вычищено из трёх файлов и объявлено
+    снятым, а в заголовке PR и в заголовке коммита осталось — владелец прочитал именно его.
+
+- **Число в тексте пересчитывается командой в том же коммите, где пишется.** Оно стареет
+  внутри одной ветки: «шестнадцать пар» стало неправдой через два коммита после того, как
+  было написано, и нашёл это владелец, а не проверка. Число, которое придётся пересчитывать
+  при каждой правке, лучше не писать вовсе. Число, полученное разбором текста, сверяется на
+  выборке руками до того, как его называют: разбор, не знающий второй формы записи, ошибается
+  молча — «51 пункт без задачи» оказался шестью, потому что номер стоял и отдельной строкой, и
+  в заголовке подраздела.
+- **Названная в тексте проверка запускается, а не пересказывается.** «Проверка есть» и
+  «проверка проходит» — разные утверждения, и второго в тексте обычно нет вовсе. Из четырёх
+  проверок, названных правилом, три оказались не в том состоянии, в каком текст их описывает:
+  одна отдавала полтора десятка замечаний, вторая переписывала файлы самим запуском, третья
+  была красной и роняла общую сводку вместе с собой. Ни одна из трёх не входила в выкатку,
+  поэтому молчание было полным. Проверку, которая переписывает файлы, запускают на чистом
+  дереве: иначе её правки уедут чужим коммитом.
+- **Сделанность читается по дереву, а не по тексту, который о ней написан.** Это верно в обе
+  стороны: строка про README обеих либ была вычеркнута как сделанная, а README остался с
+  прежним числом импортёров; задача, названная владельцу несделанной, оказалась наполовину
+  закрытой и покрытой сценариями хука. Пункт плана и тело задачи описывают день, когда их
+  написали, и с тех пор не менялись.
+- **Комментарий в файле — такое же утверждение, как строка в документе.** Обоснование «строки
+  идут во всю ширину панели, иначе подсветка обрывается» было выдумано, прожило три сессии и
+  каждый раз читалось как основание вёрстку не трогать.
+- **Чужие проекты не упоминаются нигде** — ни имени репозитория, ни «портировано из», ни
+  ссылок на его файлы. Описывается то, что код делает здесь, в терминах этого проекта.

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

@@ -0,0 +1,50 @@
+# Поставка — холодная часть
+
+Ловушки: грабли, на которые уже наступали в дереве на Azure DevOps. Грузится не вместе с
+правилом, а по требованию — при обычном решении она не нужна.
+
+Правило — `git-workflow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится вторым рабочим элементом, здесь нет: делится то, что придётся откатывать порознь.
+  Сплошная правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать
+  два рабочих элемента, закрывать два PR и переносить коммиты по одному с двумя конфликтами.
+  Одна из трёх не дала коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей
+  под ветку тоже.
+- **Рабочий элемент заводится командой, а не вызовами подряд.** Доска показывает элементы своей
+  области и итерации, и заведённый мимо них в очереди работ не виден: со стороны это выглядит
+  так же, как незаведённый. Команда заведения ставит все поля разом — род, состояние,
+  исполнителя, область и итерацию, — и печатает готовую строку заведения ветки. Замеченный по
+  ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
+- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** Прогон
+  заводится и кончается на разборе файла, не начав ни одного задания: в списке он стоит
+  отказом, а внутри нет ни задания, ни лога — читается только длительность. Поэтому список
+  прогонов ветки смотрится тем же движением, что и пуш: `az pipelines runs list` по своей
+  ветке.
+- **`online` у агента на своей машине означает запущенный процесс, а не работающий конвейер.**
+  Две стороны сходятся отдельно: требования заданий и возможности самого агента в его пуле.
+  Пока пересечения нет, агент стоит `online` и не берёт ничего, а задания ждут размещённого
+  пула — по состоянию это выглядит настроенным. Владельцу называют выполненное задание с его
+  номером, а не строку состояния.
+- **Вход в реестр образов из агента, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

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

@@ -0,0 +1,78 @@
+# Поставка — холодная часть
+
+Ловушки: грабли, на которые уже наступали в дереве на GitHub. Грузится не вместе с
+правилом, а по требованию — при обычном решении она не нужна.
+
+Правило — `git-workflow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
+  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
+  закрывать два PR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
+  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
+- **Задача заводится командой, а не четырьмя вызовами подряд.** Борда к репозиторию не
+  привязана, и задача попадает на неё только явным добавлением: две задачи так и простояли вне
+  очереди работ, потому что шаг переписывали руками. Команда заведения делает все четыре — issue,
+  номер в его заголовке, добавление на борду, начальную колонку, — и печатает готовую строку
+  заведения ветки. Замеченный по ходу дефект проходит тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор PR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: PR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца. Разница между читающим и
+  пишущим вызовом в самом тексте команды не видна: личность приходит окружением, поэтому у
+  вызова на запись токен называется явно, а открытая заявка проверяется ответом хостинга о её
+  авторе — напечатанная ссылка говорит, что заявка создана, и молчит о том, кем. Чинится это
+  только переоткрытием: автора у заявки не сменить.
+- **Невалидный файл конвейера виден прогоном нулевой длительности сразу после пуша.** GitHub
+  заводит такой прогон и на ветке, на которую ни один триггер не подписан: в списке он стоит
+  отказом, а внутри у него нет ни задания, ни лога — читается только длительность. Поэтому
+  список прогонов ветки смотрится тем же движением, что и пуш — `gh run list --branch <ветка>`.
+  Один такой отказ простоял в списке до мержа, и на него никто не посмотрел: выкатка после
+  мержа отказала ровно тем же.
+- **Прогон, не вставший на пуш, возвращается повтором события, а не разбором ветки.** Замером
+  проверены обе законные дороги: и открытие PR, и пуш в уже открытый PR прогон заводят —
+  текстовый коммит и учётная запись, которой пушат, тут ни при чём. Пропавшие события пришлись
+  на час, когда хостинг отвечал `429` на загрузке действия и `503` на API, а списком прогонов
+  «не завёлся» от «не создан» не отличить. Поэтому вершину без прогона называет сверка очереди
+  работ, а событие возвращается новым коммитом либо перезакрытием PR.
+- **Красное на шаге подготовки задания — отказ хостинга, а не дефект ветки.** Раннер не смог
+  скачать действие чекаута и получил `429 Too Many Requests`; до кода прогон при этом не дошёл
+  вовсе. Лечится перезапуском прогона, и от красного по существу отличается тем, на каком шаге
+  оно встало: три прогона одного дня упали именно так.
+- **Контекст `runner` в `env` задания отбивает весь файл конвейера.** Там доступны только
+  `github`, `needs`, `strategy`, `matrix`, `vars`, `secrets` и `inputs`; `runner` появляется на
+  уровне шага, где то же значение приходит переменной окружения. Такой файл не принимается
+  вовсе: прогон кончается за ноль секунд, не начав ни одного задания. Разбор YAML этого не
+  ловит — синтаксис верный, а доступность контекстов синтаксисом не является.
+- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
+  конвейер.** Две стороны сходятся отдельно: `runs-on` у заданий и метки самого раннера. Пока
+  пересечения нет, раннер стоит `online` и не берёт ничего, а задания уходят в облако — по
+  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
+  не строку состояния.
+- **Раннер на своей машине делает прогон общим ресурсом, и стенд у прогонов один.** Порт,
+  имя базы и каталог сборки зашиты в дереве одним значением на всех: два прогона разом
+  поднимают два стенда на один порт, и второй падает целиком. Дороже всего не падение, а его
+  вид — в отчёте оно выглядит десятком красных спек про экраны, то есть дефектом правки,
+  которого нет; три прогона подряд так и упали на трёх ветках, не тронувших кода. Лечится с
+  двух сторон сразу: конвейеру объявляется группа очереди на всё дерево, а имена стенда
+  читаются из окружения с нынешними значениями в умолчании — иначе прогон и гейт пуша, зовущий
+  ту же команду, столкнутся и при очереди. Одной очереди мало, одних имён — тоже: прогоны делят
+  ещё диск, кэш сборщика и демон образов.
+- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

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

@@ -0,0 +1,49 @@
+# Поставка — холодная часть
+
+Ловушки: грабли, на которые уже наступали в дереве на GitLab. Грузится не вместе с
+правилом, а по требованию — при обычном решении она не нужна.
+
+Правило — `git-workflow`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **Одна работа — одна задача, сколько бы файлов она ни задела.** Числа, за которым правка
+  становится второй задачей, здесь нет: делится то, что придётся откатывать порознь. Сплошная
+  правка текстов дерева была заведена тремя задачами «по объёму» — пришлось стирать две,
+  закрывать два MR и переносить коммиты по одному с двумя конфликтами. Одна из трёх не дала
+  коммита вовсе: правка тел уже заведённых задач веткой не бывает и задачей под ветку тоже.
+- **Задача заводится командой, а не вызовами подряд.** Доска показывает те issue, чью метку
+  знает, и задача без метки списка в очереди работ не видна: со стороны это выглядит так же, как
+  незаведённая. Команда заведения ставит всё разом — issue, номер в его заголовке, метку списка,
+  исполнителя, — и печатает готовую строку заведения ветки. Замеченный по ходу дефект проходит
+  тот же путь.
+- **Ветка заводится вторым вызовом, а не тем же.** Гард главной ветки отклоняет составную
+  «создать ветку и сразу коммитить» целиком: ветки в момент разбора ещё нет.
+- **Сторона конфликта бывает удалением, и «сохранить обе стороны» заводит второе объявление.**
+  Главная ветка снимает объявление, потому что символ переехал, — в конфликте это выглядит как
+  сторона, которая ничего не дописала. Разбирается чтением версии главной ветки целиком, а не по
+  хунку, и сверяется проверкой повторов: обе копии сами по себе исправны, сборка и линт зелёные.
+- **Учётная запись для пуша и автор MR выбираются отдельно.** Если пушить пришлось из-под другой
+  записи, на следующий вызов это не переносится: MR открывают токеном учётной записи машинной
+  работы, и от того, чьей записью он открыт, зависит, кого можно назначить ревьювером. Однажды
+  смена записи ради пуша утекла в публикацию — PR вышел от владельца.
+- **Невалидный файл конвейера виден отказом сразу после пуша, а не упавшим заданием.** Конвейер
+  на такой файл не заводится вовсе: в списке стоит запись об ошибке разбора, а внутри нет ни
+  задания, ни лога. Поэтому список конвейеров ветки смотрится тем же движением, что и пуш —
+  `glab ci list --branch <ветка>`, — а сам файл до пуша судит проверка `.gitlab-ci.yml` в
+  проекте.
+- **`online` у раннера на своей машине означает запущенный процесс, а не работающий
+  конвейер.** Две стороны сходятся отдельно: `tags` у заданий и теги самого раннера. Пока
+  пересечения нет, раннер стоит `online` и не берёт ничего, а задания ждут общего раннера — по
+  состоянию это выглядит настроенным. Владельцу называют выполненное задание с его номером, а
+  не строку состояния.
+- **Вход в реестр образов из раннера, запущенного службой, отказывает молча.** Служба идёт без
+  сеанса пользователя, а клиент реестра уходит в системный помощник хранения ключей и получает
+  отказ во взаимодействии — задание падает до сборки. Свой каталог настроек с пустым помощником
+  не спасает: клиент переписывает пустое значение обратно сам. Готовые команды — паттерн
+  `git-workflow-docker`.
+- **Новое рабочее дерево получает только то, что лежит в индексе.** `git worktree add`
+  разворачивает коммит, а настройки, ключи, локальные разрешения и зависимости в коммит не
+  входят: свежее дерево выглядит готовым и упирается в нехватку не сразу, а на первом гарде,
+  которому нужен ключ. Что именно переносится руками, названо списком в компаньоне правила, и
+  список пополняется тем же движением, которым заводится новый файл вне индекса.

package/assets/pitfalls/spec-driven.md

@@ -0,0 +1,36 @@
+# Документация проекта — холодная часть
+
+Ловушки: грабли, на которые уже наступали. Грузится не вместе с правилом, а по
+требованию — при обычном решении она не нужна.
+
+Правило — `spec-driven`; статьи, которыми держится закон, стоят там.
+
+## Ловушки
+
+- **`tasks.md` в спеке не заводить.** Шаги — артефакт сессии, им место в ветке или в описании
+  PR. Как только в директории появляются «шаги», спек снова становится планом и умирает после
+  мержа.
+- **Спек описывает установившееся, а не предстоящее.** Единственное место, где он говорит о
+  будущем, — `proposed/<фича>/`. После выкатки его текст вливается в спек домена, директория
+  удаляется, идентификаторы сценариев не меняются.
+- **Семантику полей не сверяет ничто.** Проверка знает имена процедур, коды отказа и связь
+  сценариев с тестами; что означает пустое поле — не знает. Правка `.proto` поэтому тянет
+  спеки всех доменов, чьи процедуры она задела, в той же ветке.
+- **Живость символа считается совпадением имени по всему дереву, а не вызовом.** Символу
+  хватает второго упоминания где угодно — в чужом поле с тем же именем, в атрибуте разметки.
+  Место, где правило исполняется на самом деле, подтверждается только чтением кода.
+- **Якорь в `tools/*.mjs` сверяется почти ничем:** живость считается только для `.ts`, а
+  исходники обходятся по `apps`, `libs` и `prisma`. Правило, привязанное к проверке, поэтому
+  читается вместе с её телом.
+- **Зелёная проверка не значит, что структура верна.** Спутники с привязкой сначала лежали
+  рядом с законами, и проверка была зелёной именно потому, что структура совпадала с тем,
+  чего проверка сама и ждала.
+- **Конфликт мержа в спеке разрешается сохранением обеих сторон, а не выбором одной.** Две
+  ветки дописывают в конец одних и тех же списков — сценариев, правил, строк привязки, — и
+  обе стороны верны: конфликт здесь не спор, а две дописи в одно место. Номера сценариев при
+  разрешении не пересчитываются: идентификатор — ключ связи с тестами, и сдвиг номеров рвёт
+  сверку у соседей, которых правка не касалась. Порядок сохранённых сторон держится
+  одинаковым в `spec.md`, `scenarios.md` и `implementation.md`: иначе правило, его сценарий и
+  его привязка перестают находиться друг по другу. После разрешения гоняется
+  `npm run check:specs` — конфликт в спеке кода не задевает, и ни сборка, ни линтеры его не
+  увидят.