agent-quality-kit 0.8.0 → 0.10.0

package/kit/docs/api-e2e.md

@@ -0,0 +1,214 @@
+# Контракт API и e2e: как сделать проверку, которая может провалиться
+
+> **Кому.** Агенту, который собирается «написать e2e для API», и человеку, который будет решать,
+> доказывает ли этот e2e хоть что-нибудь. Файл отвечает на один вопрос: **что должно получиться,
+> чтобы это была проверка, а не строка в логе.**
+>
+> Всё, что здесь названо числами, замерено на стенде 2026-09-09, а не пересказано.
+
+## Один стенд, три ответа
+
+Стенд: спецификация OpenAPI и сервер, который **врёт в каждом поле ответа** — `id` строкой
+вместо числа, обязательного `email` нет вовсе, `created_at` не дата. При этом пятисоток нет,
+коды ответа честные. Ровно так выглядит настоящее расхождение: не падение, а тихое расхождение.
+
+| Инструмент | Код возврата | Что сказал |
+|---|---|---|
+| `spectral` (набор `spectral:oas`) | **0** | нет контакта, нет описания операции, нет тегов |
+| `schemathesis`, умолчания | **1** | три нарушения схемы в ответах + принят невалидный запрос |
+| `schemathesis -c not_a_server_error` | **0** | «18 из 18 прошли» |
+
+Три вывода, и каждый стоит своей строки.
+
+1. **Линтер спецификации — не проверка сервера.** Он читает документ. На сервере, который врёт
+   в каждом поле, он остаётся зелёным и жалуется на отсутствие тегов. Это не недостаток
+   инструмента: он отвечает на другой вопрос.
+2. **`schemathesis` с умолчаниями — настоящий арбитр.** У него по умолчанию включены **все**
+   проверки, включая `response_schema_conformance`.
+3. **Сужение до `not_a_server_error` — не настройка, а отключение.** Тот же сервер, та же
+   спецификация, восемнадцать из восемнадцати прошли.
+
+## Семь вопросов о договоре — и кто на какой отвечает
+
+Подменять один вопрос другим нельзя: зелёный ответ на первый ничего не говорит о втором.
+
+| Вопрос | Чем отвечают | Чем краснеет |
+|---|---|---|
+| Документ хорошо написан? | `spectral`, `redocly`, `vacuum`, `openapi-spec-validator` | нарушение правил оформления |
+| **Сервер не ушёл от документа?** | `schemathesis`, `dredd`, `portman`+`newman` | ответ не сходится со схемой |
+| Вчерашний клиент переживёт выпуск? | `oasdiff breaking --fail-on ERR` | убрали поле, сузили тип, добавили обязательный параметр |
+| Потребитель порождён договором? | `openapi-typescript`, `orval`, `oapi-codegen`, `kubb` | сборка клиента ломается на расхождении |
+| Документ не отстал от кода? | `manage.py spectacular --fail-on-warn`, `tsoa spec` + `git diff --exit-code` | схема в репозитории не совпала с порождённой |
+| Объявленная охрана и правда стоит? | `schemathesis` (проверка `ignored_auth`, включена по умолчанию) | путь объявлен под охраной, а пускает без токена или с мусорным |
+| **Чужое не отдаётся?** | никто из перечисленных — только свой прогон от ДВУХ пользователей | второму отдали объект первого |
+
+Второй вопрос — главный и он же чаще всего не задан. Первый задают почти все: линтер ставится
+одной строкой и красиво выглядит в отчёте. Последний не задаёт ни один инструмент из списка, и
+это не их недоработка: схема описывает форму, а не право (замер — ниже).
+
+## Порядок для агента: как построить e2e, который что-то доказывает
+
+**1. Арбитр — до кода, и он обязан покраснеть.** Проверка, которую написали после кода и
+которая сразу зелёная, не проверена ни разу. Убедись, что она краснеет: сломай ответ нарочно
+(`id` строкой вместо числа) и посмотри на код возврата. Не покраснела — её нет.
+
+**2. Через настоящий порт, а не через тестовый клиент.** И вот точная граница, потому что здесь
+обычно врут в обе стороны. Тестовый клиент (`TestClient`, `APIClient`, `supertest` без сервера)
+**проходит через приложение целиком** — промежуточные слои, обработчики ошибок, внедрение
+зависимостей. Он не проходит через **дорогу к приложению**:
+
+- обратный прокси и его правила: срезанные заголовки, лимит тела запроса, таймаут, сжатие;
+- TLS и то, что за ним: настоящий `Host`, схема, порт;
+- сервер приложений и его настройка: число процессов, keep-alive, размер очереди;
+- настоящая сериализация по проводу: то, что клиент увидит байтами, а не объектом в памяти;
+- окружение: переменные, которых в тестах нет, и наоборот.
+
+Мок-тесты слепы на швах ровно этого списка. Поэтому: **хотя бы один прогон — `curl` по
+настоящему адресу**, а не только тестовый клиент.
+
+**3. Проверяй состояние, а не текст ответа.** «Ответ 200» и «заказ создан» — разные утверждения.
+Арбитр смотрит на внешний признак: строка в базе, файл на диске, событие в очереди. Ответ
+сервера — то, что подделать проще всего.
+
+**4. «Не 500» — не проверка.** Это самая частая подмена. Сервер, который врёт в каждом поле,
+отвечает двумястами. Смотри `response_schema_conformance`, а не отсутствие падений.
+
+**5. Проверяй от ДВУХ пользователей, а не от одного.** Это не про полноту, это про целый класс
+дыр, невидимый по построению. Замер ниже показывает: сервер, который отдаёт любому чужой заказ,
+проходит сверку контракта целиком — 44 из 44, код 0. Один пользователь не может обнаружить, что
+ему отдали чужое: чтобы это увидеть, нужен второй, чьи данные попробуют забрать. Самая частая
+дыра в API (`BOLA`, около 40% атак) видна только так.
+
+**6. Данные теста не общие.** Самый частый отказ в e2e — общие изменяемые данные: один прогон
+создал запись, другой ждал, что её нет. Три рабочих уклада: сброс базы к известному состоянию
+перед набором; свой счёт на каждый прогон, создаваемый и удаляемый через само API; свой счёт на
+каждого параллельного исполнителя. Плохо — один вечный тестовый пользователь на всех.
+
+**7. Тест не правится ради зелёного.** Когда арбитр краснеет, у пишущего два выхода: починить
+код или ослабить арбитра. Второй дешевле и с виду неотличим от первого. Этот класс сторожат
+записи `test-not-adjusted` и `gate-not-weakened`.
+
+## Что сверка контракта ловит, а что не увидит никогда
+
+Второй стенд. Сервер **безупречен по контракту**: токен требует, мусорный токен отвергает, кривой
+ввод отвергает, на неописанный метод отвечает `405` с заголовком `Allow`, ответы точно по схеме.
+Дыра ровно одна и настоящая: **любой заказ отдаётся любому, кто спросил** — чужой в том числе.
+
+| Что подсадили | Что сказал `schemathesis` |
+|---|---|
+| схема объявляет охрану, сервер токен не спрашивает | **поймал**: «API accepts requests without authentication» |
+| сервер принимает мусорный токен | **поймал**: «API accepts invalid authentication» |
+| сервер отдаёт любому чужой заказ | **44 из 44 прошли, код 0** |
+
+Первые две строки — приятная неожиданность: сверка контракта нашла настоящую дыру в охране,
+причём с умолчаниями и без единой настройки. Обещание «этот путь под охраной» — такое же
+обещание, как тип поля, и у него теперь есть сторож.
+
+Третья строка — граница, и её надо знать наизусть. **Схема описывает форму, а не право.**
+«Заказ существует и выглядит как заказ» и «этот заказ можно показать этому человеку» —
+утверждения из разных миров, и второе машина из документа не выведет. Отсюда правило 5 выше:
+проверка от одного пользователя этот класс не видит вовсе, сколько её ни гоняй.
+
+## Моки расходятся с сервером молча
+
+Мок, написанный руками, расходится с сервером в тот день, когда сервер меняют, — и тест
+продолжает проходить. Это тот же класс, что вся эта методичка: зелёное, которое ничего не значит.
+
+- мок, **порождённый из спецификации** (`prism`, `microcks`), расходится меньше по построению:
+  он врёт ровно настолько, насколько врёт спецификация;
+- мок, **написанный руками** (`wiremock`, `mockserver` с ручными заглушками), не связан с
+  реальностью ничем, кроме памяти того, кто его писал;
+- дешёвый сторож расхождения: ночной прогон небольшого набора **против настоящего сервера**.
+  Прошёл на моках и упал на сервере — моки разошлись, и это видно в тот же день, а не в проде.
+
+## Договор об ошибках — тоже договор
+
+Спецификации почти всегда описывают успех и молчат про отказ. А клиент живёт отказами: он должен
+отличить «повтори позже» от «так нельзя никогда». Есть готовый формат — **RFC 9457
+(`application/problem+json`)**, поля `type`, `title`, `status`, `detail`, `instance`; его отдают
+из коробки Spring Boot 6+ и ASP.NET Core 7+. В сам стандарт OpenAPI он не входит — его описывают
+как обычную схему ответа.
+
+Практический смысл прямой: **описанный код ответа проверяется, неописанный — нет.**
+`status_code_conformance` краснеет на коде, которого нет в схеме, — то есть документируя только
+`200`, вы выводите из-под проверки всё остальное поведение сервера.
+
+## Pact: когда договор нужен со стороны потребителя
+
+`OpenAPI` — обещание сервера: «вот всё, что я умею». `Pact` — заявление потребителя: «вот то, чем
+я на самом деле пользуюсь». Второе обычно составляет малую долю первого, и ломается на практике
+именно оно.
+
+- **публичный API с неизвестными потребителями** — только OpenAPI: опереться могли на любое поле;
+- **несколько своих потребителей** — `Pact` точнее и дешевле в проверке;
+- **двусторонний вариант** (провайдер публикует свою спецификацию и сам доказывает, что ей
+  соответствует; потребители публикуют свои куски; сверяет их брокер, без общего прогона)
+  существует только в платном `PactFlow` — в открытом брокере его нет. Это стоит знать до, а не
+  после выбора;
+- цена настоящая: брокер, `can-i-deploy` в выкатке, дисциплина. Для трёх сервисов дороже пользы,
+  для сорока — не обсуждается.
+
+## Пять способов, которыми проверка контракта врёт
+
+Все пять — с замером или с чужим отказом, а не «бывает и такое».
+
+**1. Линтер вместо сверки.** Стоит `spectral`, галочка «контракт проверяется» есть, сервер с
+документом никто не сравнивал. Замер выше: код 0 при сервере, который врёт везде.
+
+**2. Арбитр сужен.** `--checks not_a_server_error`, один метод, три примера. Замер: «18 из 18
+прошли». Сужение выглядит как настройка и работает как выключатель.
+
+**3. Совещательный режим.** `continue-on-error: true`, `allow_failure: true`, `|| true`. Шаг
+выполняется, вердикт не выносится. Это `ci-actually-fails`, и до 2026-09-09 он не знал ни одного
+инструмента про API: три шага — фаззер, `oasdiff` и `pact`, все три обезврежены, — и он говорил
+«чисто».
+
+**4. Громкий вывод и нулевой код.** Самый коварный. Замер: `oasdiff breaking` на паре
+спецификаций, где из ответа убрано обязательное поле, печатает
+`1 changes: 1 error … removed the required property` — и **выходит с нулём**. С `--fail-on ERR`
+на той же паре код 1. Человек, читающий лог, видит красное; конвейер видит зелёное.
+
+**5. Договор описывает четверть кода.** Спецификация порождается из кода, генератор ругается,
+часть обработчиков в неё не попадает — и фаззер честно проверяет то, что до него дошло. Отказ
+чужой и с числами: 202 ошибки генерации, 37 обработчиков выброшено целиком, при этом в отчёте
+стоит «фаззинг API ✅». Лечится там же, где возникает: `--fail-on-warn` у генератора.
+
+## Спецификация из кода и спецификация руками — разные риски
+
+**Порождается из кода** (`drf-spectacular`, FastAPI, `tsoa`). Расхождение с кодом невозможно по
+построению — зато возможна **дыра**: обработчик, который генератор не понял и молча выбросил.
+Сторож — `--fail-on-warn` при генерации и коммит порождённого файла с `git diff --exit-code` в
+конвейере: тогда «схема отстала» становится красным, а не разговором.
+
+**Пишется руками** (спецификация впереди кода). Дыр нет — есть расхождение: документ живёт своей
+жизнью. Сторож — `schemathesis` против настоящего сервера.
+
+Уклад выбирается проектом; беззащитны оба, если не назвать сторожа.
+
+## Чего машина не проверит
+
+- **Право, а не форму.** Кому можно показывать этот объект — не выводится из схемы.
+  Замерено: 44 из 44 прошли на сервере, отдающем чужие заказы. Лечится не инструментом, а
+  прогоном от двух пользователей.
+- **Что договор описывает ЭТОТ сервер.** Файл может описывать чужой API.
+- **Что арбитр смотрит на то, что важно.** Схема сходится, а поле означает не то — это разбор
+  человеком, а не проверка.
+- **Что e2e прошёл по важному пути.** Покрытие путей арбитром не считает никто из перечисленных.
+- **Смысл ломающей правки.** `oasdiff` скажет «поле убрано»; нужно ли его убирать — решение.
+
+## Что из этого сторожит комплект
+
+| Запись | Что ловит |
+|---|---|
+| `api-contract-has-arbiter` | спецификацию не держит ни одна команда; арбитр не может провалиться |
+| `ci-actually-fails` | шаг с проверкой контракта под `continue-on-error` или `\|\| true` |
+| `test-not-adjusted` | арбитра ослабили, чтобы стало зелёным |
+| `promise-has-gate` | обещание в своде без названного сторожа |
+
+Остальное из этого файла машиной не проверяется — и написано именно поэтому.
+
+**Почему записи каталога нет на «две учётки» и на «моки разошлись».** Проверить это машиной
+можно только догадкой: по коду теста не видно, два ли в нём пользователя и настоящий ли за ним
+сервер. Запись, которая красит по догадке, ошибается на законном укладе — а гейт, ошибающийся на
+законном, выключают целиком, вместе с тем, что он ловил верно. Здесь дешевле текст, который
+человек прочтёт один раз, чем сторож, которому перестанут верить.

package/kit/docs/ready-made-rules.md

@@ -197,6 +197,58 @@ npm install -g agnix && agnix --strict .
 настройкам нашёл шесть таких хуков в четырёх репозиториях — среди них `typecheck && test` перед
 коммитом, не запускавшийся ни разу. Это запись `hook-actually-fires`.
 
+Тот же класс у MCP: объявленный сервер, который не поднимается, агенту не виден никак — у него просто нет этих инструментов. Запись `mcp-server-resolves` ловит две самые частые смерти без запуска: команды по абсолютному пути, которой больше нет, и версии, которая не закреплена и приезжает новая при каждом запуске.
+
+## Поиск на большом репозитории: `tgrep`, и как им пользоваться правильно
+
+Переносимые проверки каталога ищут через `grep`. На проекте до нескольких тысяч файлов это
+десятки миллисекунд, и менять там нечего. **От десятка тысяч файлов картина другая.**
+
+[`tgrep`](https://github.com/microsoft/tgrep) — Microsoft, MIT, Rust: строит триграммный индекс
+и держит фоновый сервер, следящий за изменениями. Замер 2026-09-09 на настоящем проекте, один
+и тот же набор файлов, одна и та же регулярка:
+
+| файлов в проекте | `grep` | `tgrep` |
+|---|---|---|
+| 277 | **6 мс** | индекс строится дольше, чем идёт поиск |
+| 1 737 | **39 мс** | 77 мс |
+| 37 760 | 96 мс | **16 мс**, полнота полная |
+
+Перелом между двумя и десятью тысячами файлов. Их собственные замеры — на 96 000, 388 000 и
+504 000 файлов, где выигрыш доходит до пятидесяти раз; заявка честная и подтверждается.
+
+### Две грабли, на которые мы наступили сами
+
+**Первая: по умолчанию он не видит точечные каталоги.** Индекс строится по видимым файлам, и
+`.claude/`, `.github/`, `.env.example` для него не существуют. На нашем замере это было 32
+найденных файла вместо 55 — и узнали мы это только сверкой со списком `grep`, а не из вывода.
+Лечится флагом **при индексации**, а не при поиске:
+
+```bash
+tgrep index . --hidden     # без --hidden точечные каталоги не попадут в индекс
+tgrep serve .              # демон следит за изменениями
+tgrep "что ищем" .         # мгновенно, полнота как у grep
+```
+
+**Вторая: `--hidden` при ПОИСКЕ отключает индекс.** Это написано в их документации, раздел
+«Flags that bypass the index», и мы это пропустили: первый замер дал «7 секунд, медленнее
+grep» — потому что мерили обход дерева, а не индекс. Флаг ставится один раз, на `index`.
+
+### Почему он не годится арбитром гейта
+
+Проверено опытом: секрет, записанный **после** индексации, при запросе к устаревшему индексу
+не находится, и код возврата — «совпадений нет». Для гейта секретов это молчаливое зелёное на
+самом опасном месте. С работающим `tgrep serve` находится сразу — но тогда условие правильности
+гейта звучит как «на машине поднят фоновый процесс», а гейт обязан быть прав без предварительных
+условий.
+
+Плюс два расхождения, о которых стоит знать: **коды возврата как у ripgrep** (`0` — совпадение
+найдено, у гейтов наоборот) и **файлы больше 64 МиБ пропускаются** по умолчанию.
+
+Вывод простой: **инструмент для человека, а не для ворот.** Ищете руками по большому
+репозиторию — ставьте. Проверяете код перед коммитом — `grep` честнее, потому что не зависит ни
+от чего.
+
 ## А если проект не на Python?
 
 Ничего не меняется. Запись каталога держит **одно намерение и несколько исполнителей**, и
@@ -226,6 +278,142 @@ npm install -g agnix && agnix --strict .
 | подавление проверки без адреса | наш `gate-not-weakened` плюс `eslint-plugin-eslint-comments`, `flake8-noqa` |
 | шаг конвейера, который не может провалиться | наш `ci-actually-fails`; у `checkwash` есть смежный `CI_WORKFLOW_TOUCHED` |
 
+## Три сверки под три предложенные записи — 2026-09-09
+
+Второй пользователь предложил три записи каталога (issue #46). Прежде чем писать код, проверено
+снаружи, есть ли готовое. Ответ вышел **разный по всем трём** — записано здесь, чтобы поиск не
+повторяли.
+
+### Миграция, не попавшая в журнал инструмента
+
+**Похоже, готовое есть, и запись остановлена до замера.**
+
+| Инструмент | Что делает | Закрывает ли класс |
+|---|---|---|
+| `drizzle-kit check` | согласованность истории миграций: коллизии снимков, дубли `idx` в `_journal`, непоследовательные номера | **неизвестно** — про написанный руками `.sql` без записи в журнале в документации не сказано |
+| `alembic check` | сравнивает МОДЕЛИ с миграциями: «есть ли изменения без ревизии» | нет, это другой вопрос |
+
+Замер, который решает: положить руками `migrations/9999_test.sql`, в `_journal.json` не вписывать,
+запустить `npx drizzle-kit check`. Красный — записи не надо вовсе, надо строка «поставь эту
+команду в конвейер». Зелёный — запись законна и сразу с доказательством.
+
+**Это тот случай, ради которого правило и написано:** одна команда решает, будет папка или строка.
+
+### Команда сборки, заглушившая свой отказ
+
+**Готового нет, и это проверено — причём показательно.**
+
+Ближайшее — `shellcheck SC2312`, и оно про другое: маскировку кода возврата в подстановке
+команды. Мало того, что не ловит `>/dev/null 2>&1` у сборки, — в собственном тексте правила
+`|| true` предложен **как способ подавления**:
+
+> Consider invoking this command separately to avoid masking its return value (or use `|| true`
+> to ignore).
+
+Источник: <https://www.shellcheck.net/wiki/SC2312>
+
+То есть общепринятый линтер оболочки считает `|| true` намеренным приёмом — и он прав в своей
+области. Наша запись про **место**: команда, выносящая вердикт, не имеет права молчать о своём
+отказе. `Makefile`, `package.json`, скрипты развёртывания — там `|| true` частый гость, а сторожа
+нет ни одного.
+
+### Починка без арбитра
+
+**Готовое есть, и его обязательно называть.** `danger-js` делает этот класс типовым правилом
+(«app changes without tests»), есть и плагины. Источник: <https://danger.systems/js/>
+
+Отличия настоящие, но их всего два: `danger-js` работает на уровне PR и требует GitHub плюс
+`Dangerfile`. Запись каталога смотрела бы **коммит** и не была бы привязана к площадке —
+прецедент есть, `commit-explains-itself` читает историю, а не дерево файлов.
+
+Это ровно тот случай, когда своя запись законна, но раздел «готовый аналог» обязан назвать
+чужой инструмент и сказать, **почему не он**.
+
+## Разбор истории git: кто это уже делает — 2026-09-09
+
+Прежде чем писать `aqk probe`, проверено снаружи. **Поле не пустое, и это надо знать.**
+
+| Инструмент | Что меряет | Лицензия |
+|---|---|---|
+| [CodeScene](https://codescene.com/product/behavioral-code-analysis) | горячие точки = **частота изменений × сложность** (строки кода как приближение). Плюс здоровье кода и временную связность файлов | коммерческий |
+| [code-maat](https://github.com/adamtornhill/code-maat) | то же из командной строки: горячие точки, связность авторов, возраст кода. Git, hg, svn, p4, tfs | открытый, тот же автор |
+| Hercules, git-quick-stats, git-fame, CodeCharta | статистика по истории в разных срезах | открытые |
+
+**Все они отвечают «этот код рискованный».** Ни один не отвечает на следующий вопрос: **поймает
+ли там что-нибудь брак.** Наш угол именно в этом — история скрещивается с **подсадкой**: мы
+говорим не «здесь сложно», а «здесь брак не увидит ни одна ваша проверка, вот доказательство».
+
+Второе отличие тоньше и важнее. Они берут **частоту изменений**, мы — **частоту починок**.
+Часто меняют и то, что активно пишут: растущий модуль наберёт изменений больше всех и окажется
+наверху рейтинга, не будучи ломким. **Возвращаются с починкой** — туда, где ломается.
+
+Своё писать законно ровно потому, что назван вопрос, на который готовое не отвечает. Если
+понадобится связность файлов или возраст кода — брать `code-maat`, а не писать второй.
+
+## Контракт API: самая дорогая дыра, и готовое здесь сильное — 2026-09-09
+
+**Спецификация, разошедшаяся с кодом, — это наш центральный класс, только на уровне API.**
+Документ обещает, машина не держит: `openapi.yaml` говорит, что поле обязательно, сервер отдаёт
+без него, и узнают об этом у клиента. Ровно «тишина неотличима от успеха».
+
+Своего гейта здесь быть не должно: готовое сильное и его несколько. Разница между инструментами
+— в том, на какой вопрос они отвечают.
+
+### Спецификация правильно устроена
+
+| Инструмент | Чем берёт | Цена |
+|---|---|---|
+| [`spectral`](https://github.com/stoplightio/spectral) | сложившаяся экосистема правил, привычен | тянет Node; на больших спецификациях медленный |
+| [`redocly cli`](https://github.com/Redocly/redocly-cli) | набор правил «из коробки», настроен под документацию | мнение автора зашито сильнее |
+| [`vacuum`](https://github.com/daveshanley/vacuum) | Go, самый быстрый (втрое против redocly), отчёты в формате spectral | ест больше памяти |
+
+**Важное для выбора, и это замер, а не мнение:** при ОДИНАКОВО настроенных правилах все трое
+нашли одни и те же 12 ошибок. Различаются они умолчаниями, а не способностями: на одной и той же
+спецификации `vacuum` дал 2 ошибки и 20 предупреждений, `redocly` — 6 и 5, `spectral` — 0 и 11.
+
+Отсюда практический вывод: **сравнивать их по числу находок «из коробки» бессмысленно.** Мягкое
+умолчание `spectral` — не слабость инструмента, а его настройка, и именно она делает его тем,
+что молча пропускает. Выбирается инструмент по цене (скорость, зависимости), правила — руками.
+
+### Спецификация соответствует КОДУ
+
+Это другой вопрос, и линтеры на него не отвечают вовсе: они читают документ, а не сервер.
+
+[`schemathesis`](https://schemathesis.io/) генерирует запросы из самой схемы и сообщает о
+нарушениях схемы в ОТВЕТАХ — то есть о том, что сервер ушёл от собственного контракта. Для
+спецификаций, которые давно не обновляли (а это большинство), расхождение вылезает быстро.
+
+**Это и есть проверка, которую стоит ставить порогом конвейера.** Линтер отвечает «документ
+хорошо написан», `schemathesis` — «документ не врёт».
+
+### Ломающие изменения и потребитель договора
+
+[`oasdiff`](https://github.com/oasdiff/oasdiff) сравнивает две версии спецификации и отвечает на
+третий вопрос: переживёт ли вчерашний клиент сегодняшний выпуск. **С одной оговоркой, которая
+дороже самого инструмента:** без `--fail-on ERR` он печатает находки и выходит с НУЛЁМ. Замер
+2026-09-09 на паре, где из ответа убрано обязательное поле: вывод
+`1 changes: 1 error … removed the required property`, код возврата **0**; с `--fail-on ERR` — 1.
+
+Четвёртый вопрос — есть ли у договора потребитель. `openapi-typescript`, `orval`, `oapi-codegen`,
+`kubb` порождают клиентские типы ИЗ спецификации: тогда расхождение ломает сборку, а не
+обнаруживается у пользователя. Типы, написанные руками рядом со спецификацией, — это два
+документа об одном, и расходятся они молча.
+
+Пятый — не отстал ли документ от кода там, где он из кода порождается:
+`manage.py spectacular --fail-on-warn` (флаг так и описан: «Intended for CI/CD»), `tsoa spec`
+плюс `git diff --exit-code` на закоммиченной схеме.
+
+### Чего у них нет — и наша запись
+
+Все перечисленные предполагают, что их УЖЕ запускают. Ни один не отвечает на вопрос:
+**в репозитории лежит `openapi.yaml`, а держит ли его кто-нибудь вообще?** Это ровно форма нашей
+записи `promise-has-gate`: обещание, у которого не назван сторож.
+
+Запись есть: `api-contract-has-arbiter` (2026-09-09). Условной она была ровно до того дня, когда
+нашёлся настоящий отказ — и нашёлся сразу в трёх видах: спецификацию не держит никто; арбитр
+сужен до «не пятисотка» (замер: «18 из 18 прошли» на сервере, который врёт в каждом поле);
+`oasdiff` печатает ломающие изменения и выходит с нулём. Разбор целиком — `kit/docs/api-e2e.md`.
+
 ## Если готового нет
 
 Тогда свой гейт — и в его `README.md` пишется, **что именно проверено**: какой инструмент

package/kit/gates/README.md

@@ -128,6 +128,28 @@ requires: checkwash
 (`AQK_GATES_STRICT=1`, поднят в нашем конвейере) делает такой пропуск ошибкой: на машине,
 которая инструменты сама и ставит, «нечем проверить» обязано быть красным.
 
+## Образец про секреты обязан быть узнаваем НАМИ и не узнаваем сканерами
+
+Красный образец для записи про секреты — правдоподобный ключ. Слишком правдоподобный отправить
+нельзя: защита GitHub от секретов отклоняет push целиком.
+
+```
+remote: —— Stripe API Key ——
+remote:      path: kit/gates/secrets-not-in-code/red/leak.go:4
+remote: Push cannot contain secrets
+```
+
+Проверено 2026-09-09: `sk_live_` плюс тридцать четыре знака совпало с настоящим форматом Stripe,
+и ветка не ушла вовсе. Работающий образец короче настоящего ключа: наш гейт узнаёт его по
+префиксу, а чужой сканер по длине и форме — нет.
+
+**Правило: образец подбирается так, чтобы краснел НАШ гейт и молчал чужой сканер.** Иначе запись
+нельзя ни отправить, ни принять — и автор узнаёт об этом только на push, потратив работу.
+
+**И не цитируй значение в документации.** Запись журнала, процитировавшая образец дословно,
+уронила наш же `secrets-not-in-code` — текст о секрете попал под правило о секретах. В прозе
+нужен рассказ о форме («тот же префикс, вдвое меньше знаков»), а не сама форма.
+
 ## Запись без переносимого рецепта
 
 Иногда переносимой проверки быть не может: чтобы понять, вызывают ли функцию, нужен граф

package/kit/gates/api-contract-has-arbiter/README.md

@@ -0,0 +1,63 @@
+# У спецификации API есть арбитр
+
+**Намерение.** `openapi.yaml` — это обещание чужому коду: вот поля, вот типы, вот что
+обязательно. Обещание, которое никто не сверяет с сервером, расходится с ним молча и
+обнаруживается у потребителя. Наш центральный класс, только на уровне API.
+
+**Какой отказ это поймало.** Стенд 2026-09-09: сервер отдаёт `id` строкой вместо числа,
+обязательного `email` не отдаёт вовсе, `created_at` — не дата. Пятисоток при этом нет, коды
+ответа честные. Кто что сказал на одной и той же паре «спецификация + сервер»:
+
+| Инструмент | Код возврата | Что сказал |
+|---|---|---|
+| `spectral` (набор `spectral:oas`) | **0** | нет контакта, нет описания, нет тегов |
+| `schemathesis`, умолчания | **1** | три нарушения схемы в ответах |
+| `schemathesis -c not_a_server_error` | **0** | «18 из 18 прошли» — ни одной находки |
+
+Отсюда обе красные ветки. Замер целиком — `incidents/README.md`, 2026-09-09.
+
+**Что именно проверяется.** Записи две, и вторая тоньше первой.
+
+1. **Спецификацию не держит ни одна команда.** Файл `openapi*.{yaml,yml,json}` (и `swagger*`,
+   `asyncapi*`) в репозитории есть, а ни в конвейере, ни в сборочных файлах, ни в скриптах, ни
+   в объявлении пакета нет ни одного инструмента из четырёх семей ниже.
+2. **Арбитр сужен до «не пятисотка».** `schemathesis --checks not_a_server_error` (или `-c`).
+   У `schemathesis` по умолчанию включены **все** проверки, включая
+   `response_schema_conformance`; сужение до одной — не настройка, а отключение.
+
+Четыре семьи держателей отвечают на **разные** вопросы, и подменять один другим нельзя:
+
+| Семья | Инструменты | Вопрос |
+|---|---|---|
+| сверка с сервером | `schemathesis`, `dredd`, `portman`, `newman`, `pact` | документ не врёт? |
+| линт документа | `spectral`, `redocly`, `vacuum`, `openapi-spec-validator`, `swagger-cli` | документ хорошо написан? |
+| ломающие правки | `oasdiff` | вчерашний клиент переживёт сегодняшний выпуск? |
+| потребитель | `openapi-typescript`, `orval`, `oapi-codegen`, `openapi-generator`, `kubb` | типы порождены договором, а не переписаны руками? |
+
+**Готовый аналог.** Не нашли, и это проверено. Все четыре семьи предполагают, что их **уже
+запускают**: `spectral` читает документ, `schemathesis` — сервер, `oasdiff` — две версии
+документа. Ни один не задаёт вопрос «а меня вообще кто-нибудь запускает». Это ровно форма
+записи `promise-has-gate`: обещание, у которого не назван сторож.
+
+**Чего НЕ ловит.**
+
+- **Что арбитр проверяет ПРАВИЛЬНЫЕ вещи.** Один только линтер спецификации считается
+  держателем, хотя на сервере, который врёт в каждом поле, он остаётся зелёным. Красить за это
+  нельзя: репозиторий, который публикует чужую спецификацию (клиентский SDK, описание чужого
+  API), сервером не владеет вовсе. Разбор — `kit/docs/api-e2e.md`.
+- **Провал, погашенный `|| true` или `continue-on-error`.** Это `ci-actually-fails` — там же
+  теперь опознаются и инструменты про API.
+- **Обезвреженного арбитра внутри оболочечного скрипта.** Держателя ищем и в `*.sh`, а вопрос
+  «может ли он провалиться» задаём только объявлениям запуска: конвейеру, `Makefile`,
+  `justfile`, `package.json`. Внутри скрипта вердикт решают `set -e`, `trap` и явный `exit`, и
+  по одной строке о нём судить нельзя — ту же границу проводит `ci-actually-fails`. Поймано на
+  себе: наш `smoke.sh` держит образцы в heredoc, и запись покраснела на собственном наборе
+  проверок, причём одна находка была в комментарии.
+- **Спецификацию с нестандартным именем.** `docs/api/spec.yaml` не опознаётся: имя файла —
+  единственный надёжный признак, а `spec.yaml` встречается у чего угодно. Переименуй в
+  `openapi.yaml` — так его найдут и чужие инструменты, а не только этот.
+- **Сужение другими способами.** Ограничение одним методом (`--include-method GET`), крошечное
+  число примеров, выборка путей. Это законные настройки: у проекта бывает причина не трогать
+  запись. Красным сделано только то, у чего законного применения нет.
+- **Что спецификация вообще описывает этот сервер.** Файл может описывать чужой API; сверять
+  их машина не умеет.