@rt-tools/agent-kit 0.16.0 → 0.17.0

package/assets/laws/verifiability.md

@@ -16,6 +16,17 @@
   человек его видит, лежит всё, чего проверка не касалась.
 - **Тест, выключенный признаком окружения, покрытием не считается.** В обычном прогоне он не
   исполняется ни разу, а в сводке выглядит так же, как исполненный.
+- **Тест, снимающий себя по тому, что застал на экране, покрытием не считается.** Набор, идущий
+  одной сессией, несёт состояние из теста в тест, и проверка, начинающаяся с «нужного на экране
+  нет — пропускаю», снимает себя от чужой правки, а не от своего окружения. В сводке это одна
+  строка про пропуск, а стоит за ней целая возможность.
+- **Тест приводит экран в нужное ему состояние сам и возвращает общее состояние таким, каким
+  застал.** Иначе снявшийся тест держится ровно до следующей правки соседа, а прогон называет
+  ноль падений и в тот день, когда проверка не исполнялась ни разу.
+- **Проговорённый список проверок проверкой не бывает.** Он называет замысел, а не то, что
+  ушло в команду, и оба текста пишутся одним ходом, не сверяясь друг с другом: список, названный
+  пункт за пунктом, от короткого «я проверил» отличается только длиной. Проверка — чтение
+  полученного: вывода команды, отданного текста, состояния после вызова.
 - **Упоминание в тесте сценария, которого нет, — отказ.** Так ловится переименованный или
   выкинутый сценарий: без этого он пропадает молча.
 - **Работающее приложение проверяется там, где его видит пользователь.** Отладочный режим ведёт
@@ -37,6 +48,16 @@
   Сообщение о готовности говорит лишь, что служба себя объявила: та, которой не досталось ни
   одного задания, выглядит в нём точно так же, как работающая. Проверяются обе стороны связи — что
   заказчик выбирает именно её и что задание через неё прошло.
+- **У обмена спрашивают обе стороны, и сторона, которой нет, называется прямо.** Односторонний
+  обмен выглядит рабочим с обеих сторон: отправляющая получает успех на каждый вызов, а того, что
+  прочитать результат нечем, не видно ниоткуда — молчание об отсутствующей стороне неотличимо от
+  работающего обмена. Поэтому у обмена спрашивают не «прошёл ли вызов», а «читает ли кто-нибудь
+  вторую сторону», и ответ «нечем» записывается словом, а не остаётся пробелом.
+- **Значение, объявленное одной стороной обмена, второй не пересчитывается, а берётся у первой.**
+  Две копии одного счёта расходятся молча, и обе стороны при этом отвечают успехом: одна шлёт под
+  одним значением, другая ищет под другим, и не находит ничего ни разу. Что именно объявлено —
+  признак, форма записи, способ счёта ключа — берётся у объявившей стороны целиком, а не
+  повторяется по её описанию.
 - **Причина отказа, на которой строится решение, подтверждается измерением, а не правдоподобием.**
   Объяснение, пришедшее первым, объясняет наблюдаемое не хуже верного: свойство среды и
   собственный промах выглядят в отказе одинаково, и разводит их только замер, поставленный так,

package/assets/laws/work-conduct.md

@@ -41,6 +41,15 @@
   принимается заново.** Отменённое решение следа в работе не оставляет — по результату не видно ни
   того, что его принимали, ни того, что от него отказались. Принятое заново оно расходится с
   прежним молча и стоит той же работы второй раз.
+- **Решение, которое переживёт задачу, записывается там, где оно переживёт.** Ход работы умирает
+  вместе с папкой задачи, а имя, адрес и выбранный способ, названные владельцем посреди серии
+  работ, нужны следующим её задачам. Не переехавшее решение существует только в переписке того
+  захода, в котором принято: следующий заход делает разведку честно, не находит ничего — и
+  задаёт владельцу вопрос, на который тот уже отвечал.
+- **Инструмент, названный в просьбе, входит в просьбу.** Замена его на свой — отступление от
+  просьбы, даже когда свой даёт тот же ответ: равноценность инструментов решает тот, кто просит.
+  Одинаковый результат равноценностью не является — у названного инструмента бывает видно то,
+  чего у заменителя нет вовсе.
 - **Понимание записано там, где идёт работа.** Оставленное в переписке живёт у одного участника и
   до следующего дня; работу продолжает тот, у кого этой переписки нет.
 - **Сказанное владельцем записывается его словами и задним числом не переписывается.** Пересказ
@@ -197,6 +206,12 @@
 - **Уборка за работой идёт до того, как о готовности сказано.** Всё, что работа обязана убрать за
   собой, убирается раньше просьбы включить её в общее дерево, а не после согласия. После включения
   убирать уже некому: работа перешла к следующей задаче.
+- **Постоянное указание среды исполнения слабее правила дерева.** Среда описывает своё
+  умолчание и о дереве не знает; дерево вправе его отменить и отменяет молча — тем, что говорит
+  иначе. Расхождение разрешается в пользу дерева, а не того из двух текстов, который строже
+  сформулирован или ближе стоит к делу. Опознаётся оно чтением обоих, а не проверкой: указание
+  среды приходит в заход текстом, и сличить его с правилом машине не по чему.
+
 - **Пока эпик не кончился, следующая работа не выбирается, а берётся.** Выбор, предложенный
   владельцу при назначенном порядке, — это просьба назначить его заново: он уже назначен, и
   предлагать его повторно значит отменять собственное планирование.

package/assets/patterns/browser-verification-stand.md

@@ -40,6 +40,10 @@ PORT={{prodSitePort}} node dist/apps/site/server/server.mjs
 Это не дев-сервер: гард ловит `nx|ng serve`, пакетные раннеры и статические серверы, а запуск
 собранного сервера пропускает.
 
+Поведение, зависящее от хоста — адрес владельца, увод, разный ответ на разных именах, —
+проверяется прямо здесь одним запросом с заданным заголовком. Прокси с подменой для этого не
+нужен: он добавляет ещё один процесс, чьё поведение придётся отделять от проверяемого.
+
 ## Стенд админки
 
 ```bash
@@ -107,8 +111,9 @@ docker run -d --name <префикс>-stand-nginx \
   `nginx.conf`, — файл с расширением `.conf` в смонтированном каталоге попал бы в `include`
   и уронил бы nginx на директиве `user`. Без него стенд поднимается на конфиге образа, и
   предел соединений на воркер там свой.
-- Сервер отдачи страниц отвечает `400` на чужой `Host`: все запросы идут с
-  `-H "Host: localhost"`.
+- Чужой `Host` отбивает **дев-сервер**, а не собранное приложение: прод-сборка отвечает на него
+  тем же, чем и на свой. За настоящим прокси запросы идут со своим заголовком ровно потому, что
+  прокси стоит перед дев-сервером, — оттуда и `-H "Host: localhost"`.
 - Переменные окружения стенда обязаны смотреть на процессы стенда. `CACHE_REFRESH_URL`,
   направленный на {{sitePort}}, сбрасывает кэш мимо того процесса, который держит справочник
   перенаправлений в памяти, — исправный механизм при этом выглядит сломанным.

package/assets/patterns/doc-style-write.md

@@ -69,7 +69,20 @@ description: Паттерн правила doc-style. Брать при напи
 ✓ у пустого списка должен быть текст, у отказа — кнопка повтора
 ```
 
-Проверка: прочитать фразу вслух. Если так не говорят — переписать.
+Проверка: прочитать фразу вслух. Если так не говорят — переписать. Слухом это ловится в той
+фразе, которую читают, и не ловится в файле на восемьсот строк: оборот всплывает по всему
+тексту, и глазами он не считается.
+
+Вторая половина проверки — счёт, и там, где дерево разложило проверку слога
+`checks/check-prose-style.mjs`, набор оборотов накоплен в ней самой: каждый признак назван
+вместе с заменой, а находка печатается файлом и строкой. Оборот, найденный вычиткой,
+дописывается в набор тем же ходом — иначе следующий пишущий начинает с пустого места и
+собирает его заново из своей памяти.
+
+Чего не видит ни слух, ни она: повтора законного оборота. Каждое его появление законно
+поодиночке, а стоящий в тексте десятками он уже не приём, а тик — читатель перестаёт замечать
+его вместе со смыслом. Считается это грепом по тексту, и число само по себе отказом не бывает:
+судит его тот, кто правит следующим.
 
 ## Факт проверяется, а не вспоминается
 
@@ -79,6 +92,33 @@ description: Паттерн правила doc-style. Брать при напи
 Особенно это касается отказов: «вернётся `value out of range`» продержалось в двух документах,
 хотя такой отказ недостижим — в контракте и в колонке одна ширина.
 
+**Утверждение о состоянии другой ветки читается из неё, а не из своей копии.** Копия, снятая при
+отведении, отвечает на любой вопрос о содержимом файла и ни одним признаком не показывает,
+насколько она отстала. Трижды за один заход состояние общей ветки вывели из файла на своей,
+отставшей на семь коммитов; все три вывода неверны, один доехал до документа задачи и был назван
+владельцу как факт. Поймано ребейзом, то есть случайно.
+
+```bash
+git fetch origin
+git show origin/main:<путь к файлу>
+```
+
+**Утверждение «все N таких-то» пишется после перечисления маршрутов, которыми значение попадает в
+место, а не после скана по одному образцу.** Скан подтверждает ровно тот маршрут, который в него
+заложен, и молчит обо всех прочих — тем увереннее, чем точнее образец. Посчитали места по образцу
+самого вызова, получили 22 и записали в план и в описание заявки, что порядок держится
+устройством; мимо прошли десять вызовов обёртки, которая берёт значение аргументом. Мест
+оказалось 32, и у десяти значение стояло числом.
+
+**Команда, которой получено число, проверяется на том, что она мерит спрошенное.** Вывод команды
+— не подтверждение сам по себе: инструмент отвечает на тот вопрос, который понял, и о непонятой
+части образца молчит. Три числа подряд за один заход: граница слова, не реализованная в этой
+сборке инструмента и не объявленная отказом, дала 278 вхождений вместо 79; счёт вызовов
+регулярным выражением дал 32 и 42 на одном и том же, а по синтаксическому дереву их 27.
+
+**Число, пришедшее из прошлой сессии, замером не считается.** Оно неотличимо от замеренного и в
+документе выглядит так же уверенно; пересчитывается заново тем же ходом, которым пишется.
+
 ## Не пересказывать то, у чего есть источник
 
 - типы и поля контракта — `libs/common/proto/proto/<область>/v1/`, ссылкой;

package/assets/patterns/git-workflow-commit.github.md

@@ -26,6 +26,19 @@ description: Паттерн правила git-workflow. Брать на зав
 
 Все четыре шага делает одна команда дерева, а не рука: делить их значит забывать третий.
 
+**Очередь работ спрашивается до заведения задачи, а не после.** Найденное собственной сверкой
+ощущается новым, и это ощущение — единственное, что стоит за решением завести задачу: команда
+заведения отвечает за свои вызовы и о содержании очереди не знает ничего. Спрашивается она
+поиском по словам темы, вместе с закрытым за последний месяц: дефект, закрытый и вернувшийся, —
+та же работа, а не новая. Дубль стоит дорого — по нему проходит вся работа целиком, а сводить
+две задачи в одну потом приходится руками.
+
+```bash
+/opt/homebrew/bin/gh issue list --state all --limit 200 --search '<слова темы>' \
+    --json number,title,state
+```
+
+
 ```bash
 npm run task:new -- --title 'Письма владельцу не уходят молча' \
     --label bug --label area:api --slug mail-owner-silence < описание.md
@@ -180,13 +193,13 @@ Docs-skip: правка только в тестах хука, зеркала у
   каталог диагностики.
 - `gh project` с `--owner` отвечает `unknown owner type`: владелец борды — другая учётная
   запись, и правка идёт только через GraphQL.
-- Заведённый тикет на борду сама она не забирает: репозиторий с ней не связан, и добавление
+- Заведённую задачу на борду сама она не забирает: репозиторий с ней не связан, и добавление
   идёт отдельным вызовом. Два тикета так и остались вне очереди работ — поэтому все четыре
   шага и делает `npm run task:new`, а не рука.
 - Исполнитель у задачи не проставляется сам ни при заведении через веб, ни при добавлении на
   борду: из девяноста девяти открытых задач он стоял у двух.
 - Задача, заведённая через веб, мимо команды, на борду не попадает и гардом не отбивается —
-  он смотрит команду, а не тикет. Ловится это только сверкой очереди.
+  он смотрит команду, а не задачу. Ловится это только сверкой очереди.
 - Колонка задачи сама не двигается ни от заведения ветки, ни от открытия PR: борда ветки не
   видит вовсе, а связь с PR заполняет только поле «Linked pull requests». Взятие в работу не
   ловит и сверка — ей ветка тоже не видна.

package/assets/patterns/git-workflow-docker.md

@@ -176,6 +176,20 @@ docker info --format 'демон: {{.ServerVersion}}'
 содержимым или `403`, но не `401`. Каталог снимается в конце — раннер живёт между прогонами, и
 пароль реестра остался бы лежать на диске владельца.
 
+## Права токена спрашиваются до того, как конвейер на них обопрётся
+
+Токен, которым ходят руками, и токен, которым ходит выкатка, — один и тот же ровно до первой
+записи в реестр образов: области у него могут кончаться на чтении. Узнаётся это отказом, когда
+весь путь выкатки уже написан, поэтому спрашивается раньше — и не догадкой, а заголовком ответа
+хостинга:
+
+```bash
+curl -sI -H "Authorization: Bearer <токен>" '<адрес хостинга>' | grep -i '^x-oauth-scopes:'
+```
+
+Первая выкатка, сделанная руками из-за такого отказа, путь выкатки не проверяет — она проверяет
+образы. Об этом говорится владельцу прямо: иначе зелёный прод читается как пройденный конвейер.
+
 ## Образ собирается под платформу прод-сервера
 
 Машина владельца и прод-сервер бывают разной архитектуры. Без явной платформы собирается образ

package/assets/patterns/git-workflow-merge.md

@@ -40,6 +40,23 @@ git diff --name-only --diff-filter=U     # что встало конфликт
 | компаньон правила рядом со скилом | сохранением обеих сторон — те же две дописи в одну таблицу; после — `npm run check:specs` |
 | список работ (`docs/BACKLOG.md`) | признаком отбора — паттерн `doc-style-sweep`                                       |
 
+## Коммит переносится черри-пиком
+
+Ветка, которой коммит должен был уехать, ушла: влилась, была снята хостингом или заведена не под
+ту задачу. Сам коммит при этом цел и лежит в отпавшей ветке.
+
+```bash
+GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<номер>+<бот>@users.noreply.github.com" \
+    git cherry-pick <sha>
+```
+
+Переменные подписи стоят на самой команде переноса. Черри-пик сохраняет автора коммита и ставит
+коммиттером того, кто его зовёт, — то есть человека; коммиттера читает набор проверок перед
+пушем, и чинится это уже перебазированием, а не правкой одного коммита.
+
+Отпавшая ветка снимается с обеих сторон тем же ходом — иначе она стоит в перечне как незакрытая
+работа.
+
 ## Что дописала ветка, видно только от точки расхождения
 
 Конфликтный маркер показывает место, а не правку: сторона ветки в нём — её допись вместе со
@@ -107,5 +124,6 @@ PR описывал дерево на день, когда его написал
 - Тело PR оставлено прежним: ревьювер читает утверждение о дереве, которого больше нет.
 - Раздел, снятый главной веткой, вернулся «сохранением обеих сторон»: в спеке два экземпляра
   одного абзаца, и снятый читается как действующий.
+- Черри-пик взят без переменной коммиттера: автор у коммита прежний, коммиттер — человек, и отправку отбивает набор проверок.
 - Мерж ушёл за подписью человека: переменных в команде слияния не было, а строка о подписи
   лежит ниже команды и читается уже после коммита.

package/assets/patterns/git-workflow-migration.md

@@ -74,6 +74,11 @@ npx prisma migrate resolve --applied <новое имя>
 
 ## Частые промахи
 
+- **Накат в образе настраивается файлом настройки, а не адресом в окружении.** Седьмая редакция
+  читает адрес хранилища только из своего файла настройки: ни объявление в схеме, ни переменная
+  окружения в составе прода его не заменяют. Этот файл кладётся в образ явно, рядом со схемой и
+  миграциями. Без него сборка зелёная целиком — генерация клиента на стадии сборки проходит, — а
+  отказывает первый же накат на узле.
 - Метку времени ставит момент создания, а порядок применения лексикографический: миграция из
   ветки, начатой раньше, встаёт перед той, от которой зависит. На существующей базе это
   незаметно — падает только накат с нуля.
@@ -86,3 +91,9 @@ npx prisma migrate resolve --applied <новое имя>
   через деплой, данные — через админку.
 - Строки адресуются по первичному ключу, а не по маске: удаление по маске почты однажды унесло
   вместе с тестовыми записями демонстрационные брони владельца.
+- **Формой запроса вопрос гарда не снимается.** Условие по идентификатору он судит одинаково в
+  любой записи — что по одному, что по списку, — и на обе отвечает вопросом владельцу; отказ
+  приходит только на условие не по идентификатору. Там, где вопрос читается отказом, ход один:
+  назвать владельцу отбитую команду и попросить режим, в котором вопрос дойдёт, — а не
+  переписывать запрос, пока он не пройдёт. Иначе из захода уносят вывод о требованиях гарда,
+  которых у него нет.

package/assets/patterns/git-workflow-pr.github.md

@@ -185,6 +185,11 @@ PR выбираются отдельно, и `GH_TOKEN` для публикац
 фразой владелец успевает влить PR, и всё сказанное о нём после этого — про вчерашний день. Так
 владельцу и было предложено влить то, что он влил часом раньше.
 
+Читается состояние и перед пушем в ветку, у которой есть заявка, а не только перед словом о
+ней. Влитая заявка означает, что ветки на сервере уже нет: пуш её не обновит, а заведёт заново,
+и вклад останется вне главной ветки. Ответ пуша говорит это одной строкой — отметкой о новой
+ветке вместо перечня коммитов, — и её читают: на удачную отправку такой ответ похож целиком.
+
 Открытый PR означает, что задача ждёт разбора, — колонка переставляется тем же движением:
 
 ```bash
@@ -276,5 +281,5 @@ in-review`, — и `npm run check:board` прогоняется ещё раз:
   выглядя работающей. Так шестнадцать PR ждали разбора, которого никто не запрашивал.
 - Метки поставлены по названию PR, а не прочитаны у задачи: область теряется, и по борде не
   видно, что правка задела ещё и сайт.
-- Задача закрыта не полностью, а метки перенесены целиком: тикет остаётся открытым, и это
+- Задача закрыта не полностью, а метки перенесены целиком: задача остаётся открытой, и это
   говорится в теле PR, а не подразумевается строкой `Closes`.

package/assets/patterns/git-workflow-secrets.md

@@ -17,6 +17,20 @@ description: Паттерн правила deploy-flow. Брать при раб
 - Разбирается, что именно выкачено и чего приложению не хватает для работы, — включая ключ,
   который живёт в окружении и экрана не имеет.
 
+## Секрет выкатки — не ключ внешней службы
+
+Ключи из этого паттерна живут в хранилище или в составе прода, и читает их приложение. Секреты
+выкатки — ключ доступа к узлу, пароль реестра, адрес и токен приёма — приложением не читаются
+вовсе: их читает конвейер, лежат они в настройках репозитория, и хранилище о них не знает.
+
+Отсюда и разный ход при промахе. Ключ службы, которого не хватает, молчит на экране: возможность
+не работает, а приложение отвечает. Секрет выкатки, которого не хватает, роняет шаг конвейера, и
+до приложения дело не доходит вовсе — разбирают его в журнале задания, а не в браузере.
+
+Про то, как секрет выкатки заводится и чем проверяется его право, говорит паттерн работы с
+образами — `git-workflow-docker`, если дерево его разложило. Здесь остаётся граница: пришедший
+за секретом выкатки читает дальше не этот текст.
+
 ## Ключ, заводимый владельцем, живёт в хранилище, а не в окружении
 
 Такой ключ лежит строкой в хранилище, зашифрованной ключом шифрования секретов; рядом открытая

package/assets/patterns/git-workflow-stack.md

@@ -2,7 +2,7 @@
 name: git-workflow-stack
 kind: pattern
 rule: git-workflow
-description: Паттерн правила git-workflow. Брать, когда из одного основания заведено больше двух веток и все ждут слияния: единица работы, порядок вливания, перевливание главной по факту конфликта, сложение у общих указателей. Один конфликт — паттерн git-workflow-merge.
+description: Паттерн правила git-workflow. Брать, когда работы идут одна за другой либо когда из одного основания уже заведено больше двух веток: ветвление чередой от предыдущей, основание заявки, порядок вливания снизу вверх, перевливание главной по факту конфликта. Один конфликт — паттерн git-workflow-merge.
 ---
 
 # Стопка заявок из одного основания
@@ -17,6 +17,53 @@ description: Паттерн правила git-workflow. Брать, когда
 - За заход сделано несколько работ, и они лежат в дереве невыложенными.
 - Решается, в каком порядке отдавать накопленное владельцу.
 
+## Череда: ветвиться от предыдущей, а не от главной
+
+Стопка из одного основания — то, чего надо избежать. Работы, идущие подряд, ветвятся подряд:
+
+```bash
+# первая работа череды — от главной, как обычно
+git checkout -b <КЛЮЧ>-<номер>-<slug> origin/main
+
+# каждая следующая — от предыдущей ветки, а не от origin/main
+git checkout -b <КЛЮЧ>-<следующий>-<slug> <КЛЮЧ>-<номер>-<slug>
+```
+
+Правка предыдущей лежит тогда в общем предке, и сводить два разных изменения одного файла не
+приходится вовсе. Расхождение всплывает при ветвлении — у того, у кого обе правки свои и под
+рукой, — а не при слиянии, у владельца, у которого нет ни одной.
+
+От главной ветвится первая работа череды и всякая, которая предыдущей не касается: череда — это
+про соседние работы, а не про все подряд.
+
+## Заявка череды стоит на предыдущей ветке
+
+```bash
+gh pr create --base <предыдущая ветка> --title '[<КЛЮЧ>-<номер>] <что сделано>' --body-file <файл>
+```
+
+Основанием главная не ставится: разбор тогда показывает свою правку вперемешку со всем, что под
+ней. Влитую нижнюю хостинг переносит сам — базой её заявки-наследницы становится главная.
+
+Порядок вливания стоит в теле каждой заявки строкой «стоит на #<номер>, вливать после него»:
+владелец вливает по списку, а родство веток по списку не видно.
+
+```bash
+# порядок череды целиком — снизу вверх
+gh pr list --state open --json number,headRefName,baseRefName \
+    --jq '.[] | "\(.number)\t\(.headRefName)\tна \(.baseRefName)"'
+```
+
+## Чего в череде не делают
+
+- **Историю нижней ветки не переписывают.** Ни `rebase`, ни силовая отправка: вершина верхней
+  становится достижимой из её основания, и хостинг закрывает заявку верхней как слитую — при том
+  что в главной её правок нет. Отставшая нижняя чинится вливанием главной в неё и дальше вверх.
+- **Череду не вливают из середины.** Влитая не по порядку тащит за собой всё, что под ней, — и
+  разбор той работы уже не состоится.
+- **Готовые ветки не копят.** Череда не отменяет того, что единица работы — влитая заявка: она
+  лишь делает безопасной ту длину, которая всё же накопилась.
+
 ## Единица работы — влитая заявка, а не открытая
 
 Открытый черновик работой не является: кнопка слияния у него заблокирована, в главной ветке его
@@ -65,6 +112,21 @@ docs/archive/README.md merge=union
 Сложение ставится только на указатели, где правка всегда добавляющая. На текст, который
 переписывают, оно оставит в файле обе редакции.
 
+**Сложение сторон метку сливаемости не снимает, и вливать главную по ней нельзя.** Хостинг
+считает сливаемость своим приёмом и настроек слияния не читает: ветка, тронувшая сложенный
+указатель, помечается конфликтующей всё равно. Спрошенная у него стопка отвечает «конфликтует»
+целиком, и вливание по этому ответу — то же вливание во все ветки, что и без сложения: раздел
+ниже велит вливать главную по факту конфликта, а факт этот хостинг называет про каждую ветку
+стопки. Пятнадцать заявок разом простояли так за один заход. Проверяется одной командой: то же
+слияние без драйвера даёт конфликтный маркер, с драйвером идёт чисто — значит метку держит
+указатель, а не правка.
+
+**Указатель, куда дописывает каждая ветка стопки, из стопки убирается, а не складывается.**
+Сложение — починка проявления: конфликта нет, метка есть, вливать по-прежнему приходится.
+Спрашивается это до заведения веток: отвечает ли указатель на вопрос, которого не закрывает
+обход каталога. Не отвечает — он снимается, и площадь пересечения стопки падает до настоящих
+общих файлов.
+
 ## Порядок вливания задаётся заранее и называется владельцу
 
 Порядок считается до открытия заявок — по тому, кто какие файлы правит:

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

@@ -33,6 +33,11 @@ docs/specs/<домен>/
 та же связь сценариев с тестами. Домен, у которого половина поддоменов описана, а половина
 заведена пустыми каталогами, зелёным не бывает.
 
+Работа, задевшая домен и его поддомен, пишет две договорённости, а не одну. Префикс сценариев у
+поддомена свой, а второго префикса одному спеку сверка не даёт: сценарии такой работы
+разъезжаются по двум нумерациям — по одной на каждый спек, в который вольются. Замысел называет
+обе, и вливаются они порознь, каждая в свой спек.
+
 ## Обязательные разделы
 
 `## Зачем` · `## Терминология` с подразделом `### Как это называется в интерфейсе` ·
@@ -95,11 +100,17 @@ docs/specs/<домен>/
 `Не покрыто: <причина>`, сценарий с неполным тестом — `Покрытие: частичное — <чего не
 хватает>`.
 
+Сценарий, который проверить нечем в принципе, не заводится вовсе. Пометка о непокрытом говорит
+«теста ещё нет» и обещает, что он появится; там, где проверки не существует, обещания нет, а
+помеченный сценарий висит в наборе вечно, читается как долг и заставляет каждого следующего
+заново выяснять, не пора ли его закрыть. Правило, ради которого сценарий хотели завести,
+остаётся правилом: его держат строка в компаньоне и запись в истории изменений, и этого довольно.
+
 Номер в идентификаторе живёт так:
 
 | Что случилось           | Что делается с номером                                                                               |
 | ----------------------- | ---------------------------------------------------------------------------------------------------- |
-| сценарий добавили       | берётся следующий свободный — наибольший выданный в домене плюс один, а не дырка в середине          |
+| сценарий добавили       | берётся следующий свободный — наибольший выданный **во всех ветках** плюс один, а не дырка в середине |
 | обещание изменили       | номер тот же, заголовок теста правится тем же коммитом                                               |
 | сценарий удалили        | номер остаётся пустым и новому сценарию не отдаётся; тест удаляется вместе со сценарием              |
 | номера захотелось сжать | не пересчитываются: связь с тестами держит только номер, а прогон остаётся зелёным при обеих правках |
@@ -107,6 +118,15 @@ docs/specs/<домен>/
 Номер записывается так же, как у соседей в этом же файле: сверка ищет его шаблоном, и номер,
 записанный иначе, не совпадёт ни в спеке, ни в заголовке теста.
 
+**Свободный номер ищется во всех ветках, а не в одной главной.** Соседняя работа держит свои
+номера на диске и в главную ещё не въехала: шесть номеров так раздали дважды, и двигаться
+пришлось той работе, чья договорённость не влита. Номер — единственное, чем сценарий связан с
+тестом, и отданный второй раз он оставляет старую ссылку правильной на вид и ведущей не туда.
+
+Спрашивается это командой дерева, если дерево её завело: она читает заголовки сценариев во всех
+ветках — своих и удалённых — и печатает первый свободный за наибольшим занятым. Имя команды
+называет компаньон правила.
+
 ## Порядок работы
 
 1. Задача заводится сценариями: что станет верно, когда работа закончится.
@@ -115,6 +135,10 @@ docs/specs/<домен>/
 4. `npm run check:specs` — до пуша.
 5. Приёмка идёт по сценариям, а не по пересказу правки.
 
+Правило, обещающее человеку видимый результат, подтверждается на работающем приложении, а не
+выводом из графа вызовов. Чтением подтверждаются заголовки, связь с привязками и форма данных;
+правило, которое подтвердить не на чем, уезжает открытым вопросом и утверждением не пишется.
+
 ## Частые промахи
 
 - Выросший домен делят на новые домены, а не на поддомены: новый домен приходится заводить в
@@ -139,10 +163,19 @@ docs/specs/<домен>/
 - Закон, названный в тексте, но забытый в строке `**Законы:**`: по закону тогда не узнать,
   какие домены на нём стоят.
 - Правка `.proto` без спеков задетых доменов: `docs-guard` отбивает такой коммит.
+- **Правило, выведенное из графа вызовов, ошибается беззвучно.** Читается оно так же уверенно,
+  как замеренное, и сверка привязки его пропускает — символ на месте, просто описывает он не то.
+  Два правила одного спека оказались перевёрнутыми: связь шла не между хранилищами, а через
+  слушающий их компонент, — и оба чуть не стали задачей на дефект, которого нет.
+
 - **Выросший домен делится на поддомены, а не на новые домены.** Новый домен пришлось бы
   заводить в указателе, сверять с кодом отдельно и объяснять, чем он соседу не поддомен;
   поддомен остаётся в своём домене и наследует его контракт. Соседний домен заводится только
   тогда, когда предмет живёт своей сущностью.
+- **Наибольший выданный номер ищется по всему домену командой, а не глазами по хвосту файла.**
+  Номера в файле сценариев идут не по порядку: правки вставляли их к соседям по смыслу, и
+  последняя строка максимума не показывает. Шесть новых номеров из одиннадцати легли на занятые
+  — поймала это сверка спеков, а не чтение, и переписывать пришлось заодно заголовки тестов.
 - **Границу между доменами проводит владелец, а не автор очередной правки.** Автор видит свою
   правку, а не то, чем предмет обрастёт: домен, заведённый по ходу дела, через месяц оказывается
   половиной соседнего, и разводить их приходится вместе с номерами сценариев.

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

@@ -74,6 +74,17 @@ description: Правило под «Закон о поставке». Брат
 ---
 ```
 
+Под шапкой стоит строка требования к соседним ресурсам — тем, без которых статьи правила не
+исполняются:
+
+```markdown
+**Требует:** `hooks/<гард>.sh`, `checks/<проверка>.mjs`
+```
+
+Ресурсы называются именами пакета, а не путями дерева. Строки нет — правило не требует ничего;
+пустой она не бывает. Выводить требование из фразы в тексте нельзя: разложено у потребителя не
+всё, и текст, сказавший «правку отбивает гард», врёт в дереве, где гарда нет.
+
 Разделы: `## Как это называется здесь` · `## Где это лежит` · `## Как закон применяется
 здесь` · `## Чего из закона здесь нет` · `## Паттерны` · `## Ловушки`.
 

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

@@ -0,0 +1,57 @@
+---
+name: spec-driven-sweep
+kind: pattern
+rule: spec-driven
+description: Паттерн правила spec-driven. Брать при сплошном разборе привязки домена — пять проходов, три из которых делает машина, разбор срабатываний чтением и доля ложных по слоям. Не брать для заведения спека домена — это паттерн spec-driven-domain.
+---
+
+# Сплошной разбор привязки домена
+
+Паттерн правила `spec-driven`. Что при этом должно быть верно — закон о документации проекта.
+
+## Когда брать
+
+- Привязка домена разбирается целиком: каждое утверждение против кода, на который оно указывает.
+- Тексты дерева сверяются с деревом задачей, а не по ходу другой работы.
+
+## Проходов пять, и порядок у них один
+
+Три первых делает машина по всему домену разом, два последних — чтение. Порядок не
+переставляется: чтение идёт по строкам, которые машина уже отобрала, иначе читается весь домен.
+
+1. **Мёртвый адрес.** Названного файла нет в дереве, или символа нет нигде. Даёт ноль на домене,
+   который уже разбирали, и целую пачку на том, откуда недавно уезжал код.
+2. **Якорь, живущий только в пояснении.** Символ встречается в дереве лишь в комментариях.
+   Проверка привязки комментарий засчитывает наравне с кодом, поэтому такому якорю она зелёная, а
+   места исполнения за ним нет.
+3. **Символ не объявлен в названном файле.** Файл его импортирует и зовёт, а объявление лежит в
+   другом месте. Самый урожайный проход и самый шумный.
+4. **Обещание против кода.** Читается код по адресу: делает ли он то, что утверждает правило.
+   Машине этот проход не даётся вовсе — расхождение здесь обычно в условии и в порядке шагов.
+5. **Число, код отказа и ключ словаря — поимённо.** Каждое число из текста ищется в дереве,
+   каждый названный код отказа — в месте, где он бросается, каждый ключ словаря — во всех
+   локалях. Расхождение тут выглядит опечаткой и живёт годами.
+
+## Срабатывание — очередь на чтение, а не список дефектов
+
+Проход выдаёт строки, находкой становится подтверждённая чтением. Разница не словесная: строки
+третьего прохода на треть законны у любого домена, и записанные находками они превращают разбор в
+правку верного кода. В ход работы идут оба числа — сколько строк дал проход и сколько из них
+оказались расхождениями.
+
+## Доля ложных зависит от слоя
+
+Там, где правило живёт в процедуре, место исполнения одно и оно публично: срабатывание третьего
+прохода чаще оказывается расхождением — из четырнадцати строк шесть. Там, где правило живёт в
+компоненте или службе, местом исполнения законно бывает приватное поле или приватный метод: из
+тридцати шести строк расхождений не оказалось ни одной. Поэтому число находок прошлого домена на
+следующий не переносится — переносится только сам порядок проходов.
+
+## Ловушки
+
+- **Урожайность прохода обещана фактом.** «Проход даст столько-то» — оценка, и по чужому слою она
+  промахивается целиком. Разбор просьбы называет проходы, а не число находок.
+- **Проход, давший ноль, не записан.** Следующий заход гоняет его заново по тому же домену. Ноль
+  — такой же результат, и он пишется вместе с остальными.
+- **Счёт сторон принят за разбор.** Зелёная проверка привязки говорит, что у каждого утверждения
+  есть строка, а куда эта строка ведёт — не говорит ничего.