agent-quality-kit 0.9.0 → 0.10.0

package/README.md

@@ -87,6 +87,8 @@ aqk why <name>          what failure this guard was written for
 
 aqk prove               run every declared gate against its own samples:
                         red on the red one, quiet on the green one
+aqk probe               what the declared checks CANNOT see: plant a defect
+                        into files the fix history calls hot
 aqk report              the report form, assembled by a run
 aqk report --since main  ...plus what proves this diff, file by file
 aqk badge               write the level badge into the README
@@ -182,6 +184,7 @@ covers:                    # what a declared gate already holds — not counted
   lint: [no-print-in-prod, swallowed-error]
 samples:  gates            # a red and a green sample for every entry
 ratchets: ratchets         # debt registries: the list may only get shorter
+probe: 100                 # run the probe itself every N commits; 0 turns it off
 lessons:  incidents        # where lessons accumulate
 ```
 
@@ -268,6 +271,56 @@ The level is granted when **no provable gate is broken AND at least one is prove
 condition is not optional: a project where everything is unprovable has proven nothing — that is
 exactly what the forgery with three `true` gates looks like.
 
+### What your checks cannot see — `probe`
+
+`doctor` says "held by a machine 21". **Twenty-one out of what?** There is no denominator: 21 is
+what we happened to write into the catalogue, not what matters in your project. `prove` shows a
+gate catches a defect **on its own** sample. Neither answers the owner's question: what here is
+covered by nothing.
+
+```bash
+aqk probe
+```
+
+Two sources, both facts rather than our taste: **your repository's history** (where defects come
+back — fix commits) and the **red samples of the catalogue** (each one proven by a run). The
+sample is placed in a temporary directory at the hot file's path, and **your declared** gates are
+run against it.
+
+```
+src/mailer.py  fixes in history: 3
+  ✘  keys and passwords do not end up in the code   NOTHING CATCHES IT
+       close it: aqk add secrets-not-in-code
+  ✘  an error is not silently swallowed             NOTHING CATCHES IT
+       close it: aqk add swallowed-error
+  ✔  no "fix later" markers in finished code        caught by: todo-without-task
+```
+
+**Coverage is not declared, it is proven by planting.** This is the kit's own principle turned on
+the whole repository: a check that cannot go red is indistinguishable from an absent one. We
+demand that of every catalogue entry — and until `probe` never demanded it of a project.
+
+The measurement the command grew from, taken on the kit itself: a real source file, a swallowed
+error and a debug print planted into a copy, 21 declared gates. **Red: none.**
+
+Three states, and they do not merge: caught · **nothing catches it** · nothing to check with (the
+gate did not run, or the catalogue has no sample for that extension). The working tree is not
+touched and the exit code is always 0 — this is a look, not a threshold.
+
+**The command does not need to be remembered — that is half the design.** Once every hundred
+commits — or whatever `probe:` in the manifest says, `0` turning it off — `doctor --run` runs the
+probe **itself**, unprompted. A command you have to remember is
+the same class as a file you can fail to read: the agent will not recall it, and the human will
+never learn it exists. The unit is commits, not days: a repository nobody touched for a month
+needs no re-probe, a hundred commits in a day does. Turn it off with `AQK_PROBE=0`.
+
+The result also lands in the state block the agent reads by construction, without knowing the
+command. If no probe has ever run, it says **UNKNOWN** rather than staying silent: silence would
+read as "everything is covered".
+
+Your code is not touched — the sample lives in a temporary directory. The probe's own mark goes
+to `.aqk/last-probe.md`, next to the run report; it is ephemeral, keep it in your `.gitignore`.
+
 ## The badge
 
 ```bash
@@ -287,7 +340,7 @@ Already using [pre-commit](https://pre-commit.com)? Three lines in the file you
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.9.0
+    rev: v0.10.0
     hooks:
       - id: aqk            # runs what the repository declares; blocks below AQK-1
       # - id: aqk-doctor   # read-only: the level and what is missing, blocks nothing
@@ -308,7 +361,7 @@ layer AQK adds.
 [![on the GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.9.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.10.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -325,13 +378,12 @@ the same thing in a single line:
 A Python, Go or Rust project where nobody installed Node and nobody will:
 
 ```bash
-docker build -t aqk .                                   # from this repository
-docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" aqk doctor
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/arsen-ask-lx/aqk doctor
 ```
 
-From v0.9.0 the image is pushed to the registry by the same run that publishes the package, so
-there is nothing to build: `ghcr.io/arsen-ask-lx/aqk`. Before that tag the registry holds no
-image, and this says so plainly: a command that points at nothing is worse than no command.
+The image is pushed to the registry by the same run, from the same tag, that publishes the
+package — there is nothing to build. You can still build it yourself: `docker build -t aqk .`
+from this repository.
 
 **The `--user` flag is not decoration.** Without it the container runs as root and the files
 `init` writes end up owned by root — you cannot edit your own manifest. Measured 2026-09-09:
@@ -443,10 +495,10 @@ catalogue may grow to hundreds of entries; a given project still sees about a do
 An entry is accepted only if its arbiter goes red on the red sample, stays quiet on the green
 one, and names a real failure it caught. A machine checks this: `bash tool/selfcheck/gates.sh`.
 
-### Four entries that watch the agent, not the code
+### Five entries that watch the agent, not the code
 
 Ruff, ESLint and gitleaks already find bad code, and AQK calls them where it can rather than
-reinventing them. These four look elsewhere — at the moment the **signal** about bad code is
+reinventing them. These five look elsewhere — at the moment the **signal** about bad code is
 switched off, which is what a coding agent does when the task is phrased as "make it pass":
 
 | Entry | What it catches |
@@ -455,8 +507,15 @@ switched off, which is what a coding agent does when the task is phrased as "mak
 | `ci-actually-fails` | a pipeline step that renders a verdict but cannot fail — `run: pytest \|\| true`, `continue-on-error: true` |
 | `test-has-assertion` | a test that cannot fail: empty body, `assert True`, a skip with no reason given |
 | `promise-has-gate` | a rule in `AGENTS.md` with no enforcer named — neither a gate nor, honestly, a human |
+| `protection-not-removed` | **the instrument itself was switched off**: a gate vanished from the manifest. The declared set may only grow; removing one is allowed, but must be named |
+
+The fifth was added later, and from a bruise of our own. The first four catch the agent switching
+off a **signal**. The master switch — the manifest itself — was guarded by nothing: a measurement
+on 2026-09-09 showed that deleting one line from `.aqk.yml` turns the run green while a real
+secret sits in the code, and neither `doctor`, `report --since`, `vitals` nor the state block the
+agent reads noticed anything.
 
-Each was measured on nineteen third-party repositories (~25 000 files) before it entered the
+The first four were measured on nineteen third-party repositories (~25 000 files) before entering the
 catalogue, and two further entries were **cancelled by that measurement**: one because
 [`agents-lint`](https://github.com/giacomo/agents-lint) already does it better, one because
 91 of its 120 findings turned out to be a legitimate pattern.

package/README.ru.md

@@ -89,6 +89,8 @@ aqk why <имя>           какой отказ этот гейт поймал
 
 aqk prove               прогнать каждый объявленный гейт по его образцам:
                         красный на красном, тишина на зелёном
+aqk probe               чего объявленные проверки НЕ видят: подсадка брака
+                        в файлы, горячие по истории починок
 aqk report              форма отчёта, собранная прогоном
 aqk report --since main  ...и чем доказан этот диф, файл за файлом
 aqk badge               вписать значок уровня в README
@@ -184,6 +186,7 @@ covers:                    # что уже держит объявленный
   lint: [no-print-in-prod, swallowed-error]
 samples:  gates            # красный и зелёный образец каждой записи
 ratchets: ratchets         # реестры долга: список может только укорачиваться
+probe: 100                 # раз во столько коммитов проба делается сама; 0 — не делать
 lessons:  incidents        # где копятся уроки
 ```
 
@@ -270,6 +273,56 @@ aqk prove
 условие обязательно: проект, у которого все гейты недоказуемы, не доказал ничего — именно так
 выглядит подделка с тремя гейтами `true`.
 
+### Чего ваши проверки не видят — `probe`
+
+`doctor` говорит «держит машина 21». **Двадцать один из чего?** Знаменателя нет: 21 — это то,
+что мы успели написать в каталог, а не то, что важно в вашем проекте. `prove` доказывает, что
+гейт ловит брак **на своём** образце. Ни один из них не отвечает на вопрос владельца: что здесь
+не прикрыто ничем.
+
+```bash
+aqk probe
+```
+
+Два источника, и оба — факты, а не наш вкус: **история вашего репозитория** (где брак
+возвращается — коммиты-починки) и **красные образцы каталога** (каждый доказан прогоном).
+Образец кладётся во временный каталог по пути горячего файла, и по нему прогоняются
+**объявленные вами** гейты.
+
+```
+src/mailer.py  починок в истории: 3
+  ✘  ключи и пароли не попадают в код              НЕ ЛОВИТ НИКТО
+       закрыть: aqk add secrets-not-in-code
+  ✘  ошибка не глушится молча                      НЕ ЛОВИТ НИКТО
+       закрыть: aqk add swallowed-error
+  ✔  маркеров «доделать потом» нет в готовом коде   ловит: todo-without-task
+```
+
+**Покрытие не заявлено, а доказано подсадкой.** Это наш собственный принцип, наведённый на весь
+репозиторий: проверка, которая не может покраснеть, неотличима от отсутствующей. Мы требуем
+этого от каждой записи каталога — и до `probe` ни разу не потребовали от проекта целиком.
+
+Замер, с которого команда началась, — на самом комплекте: настоящий файл, подсаженные
+проглоченная ошибка и отладочная печать, 21 объявленный гейт. **Покраснело: ноль.**
+
+Три состояния, и они не сливаются: ловит · **не ловит никто** · нечем проверить (гейт не
+состоялся, или в каталоге нет образца под это расширение). Рабочее дерево не трогается, код
+возврата всегда 0 — это осмотр, а не порог.
+
+**Команду не нужно помнить — и это половина замысла.** Раз в сто коммитов (`probe:` в манифесте — своё число, `0` — не делать) `doctor --run`
+запускает пробу **сам**, без напоминания. Команда, о которой надо вспомнить, — тот же класс,
+что файл, который можно не прочитать: агент не вспомнит, а человек не узнает, что она есть.
+Единица — коммиты, а не сутки: репозиторий, в котором месяц не работали, перепроверять незачем,
+а сто коммитов за день — надо. Выключается `AQK_PROBE=0`.
+
+Результат попадает и в блок состояния для агента: он читает его по построению, не зная про
+команду. Пробы не было — там сказано **НЕИЗВЕСТНО**, а не пропущено: молчание прочиталось бы
+как «всё прикрыто».
+
+Ваш код проба не трогает: образец живёт во временном каталоге. Своя отметка ложится в
+`.aqk/last-probe.md` — там же, где отчёт прогона; файл эфемерный, в `.gitignore` его стоит
+держать самому.
+
 ## Значок
 
 ```bash
@@ -290,7 +343,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.9.0
+    rev: v0.10.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -309,7 +362,7 @@ repos:
 [![в GitHub Marketplace](https://img.shields.io/badge/GitHub%20Marketplace-Agent%20Quality%20Kit-2ea44f?logo=github)](https://github.com/marketplace/actions/agent-quality-kit-aqk)
 
 ```yaml
-- uses: arsen-ask-lx/Agent_Quality_Kit@v0.9.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.10.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -326,13 +379,11 @@ repos:
 Проект на Python, Go или Rust, где Node никто не ставил и не поставит:
 
 ```bash
-docker build -t aqk .                                   # из этого репозитория
-docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" aqk doctor
+docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/arsen-ask-lx/aqk doctor
 ```
 
-С версии 0.9.0 образ выкладывается в реестр тем же прогоном, что и пакет, — тогда собирать не
-нужно: `ghcr.io/arsen-ask-lx/aqk`. До этой метки образа в реестре нет, и здесь это сказано
-прямо: команда, указывающая в никуда, хуже её отсутствия.
+Образ выкладывается в реестр тем же прогоном и из того же тега, что и пакет, — собирать ничего
+не нужно. Собрать у себя тоже можно: `docker build -t aqk .` из этого репозитория.
 
 **Ключ `--user` не украшение.** Без него контейнер работает от root, и файлы, которые пишет
 `init`, достаются root — человек не может править собственный манифест. Проверено 2026-09-09:
@@ -441,10 +492,10 @@ vendor/
 Запись принимается, только если её арбитр краснеет на красном образце, молчит на зелёном и
 назван реальный отказ, который она поймала. Проверяет это машина: `bash tool/selfcheck/gates.sh`.
 
-### Четыре записи, которые смотрят на агента, а не на код
+### Пять записей, которые смотрят на агента, а не на код
 
 Ruff, ESLint и gitleaks и так находят плохой код — AQK зовёт их, где может, вместо того чтобы
-писать своё. Эти четыре смотрят в другое место: на момент, когда **сигнал** о плохом коде
+писать своё. Эти пять смотрят в другое место: на момент, когда **сигнал** о плохом коде
 выключают. Именно это делает агент, когда задача сформулирована как «сделай, чтобы прошло»:
 
 | Запись | Что ловит |
@@ -453,9 +504,15 @@ Ruff, ESLint и gitleaks и так находят плохой код — AQK з
 | `ci-actually-fails` | шаг конвейера, который выносит вердикт, но не может провалиться — `run: pytest \|\| true`, `continue-on-error: true` |
 | `test-has-assertion` | тест, который не может провалиться: пустое тело, `assert True`, пропуск без причины |
 | `promise-has-gate` | правило в `AGENTS.md`, у которого не назван сторож — ни гейт, ни, честно, человек |
+| `protection-not-removed` | **сам прибор выключили**: гейт исчез из манифеста. Набор объявленной защиты может только расти; снять можно, но названно |
+
+Пятая заведена позже остальных и по собственной шишке. Четыре первых ловят агента, когда он
+выключает **сигнал**. А главный рубильник — сам манифест — не сторожил никто: замер 2026-09-09
+показал, что удаление одной строки из `.aqk.yml` даёт зелёный прогон при секрете в коде, и этого
+не заметили ни `doctor`, ни `report`, ни `vitals`, ни блок состояния для агента.
 
-Каждая измерена на девятнадцати чужих репозиториях (~25 000 файлов) до внесения в каталог, и ещё
-две записи этот же замер **отменил**: одну — потому что
+Первые четыре измерены на девятнадцати чужих репозиториях (~25 000 файлов) до внесения в каталог,
+и ещё две записи этот же замер **отменил**: одну — потому что
 [`agents-lint`](https://github.com/giacomo/agents-lint) делает это лучше, другую — потому что
 91 находка из 120 оказалась законным приёмом.
 

package/kit/docs/ai/index.md

@@ -19,6 +19,7 @@
 | хотите понять, **как работать каждый день** | [Плейбук харнеса](agent-harness-playbook.md), раздел 18 |
 | хотите увидеть **процесс по этапам** | [SDLC эпохи агентов](ai-sdlc.md) |
 | ищете **готовое правило**, прежде чем писать своё | [Готовые правила](../ready-made-rules.md) |
+| делаете **e2e для API** и хотите, чтобы он что-то доказывал | [Контракт API и e2e](../api-e2e.md) |
 | ставите **гейты** и хотите отличить работающий от мёртвого | `kit/gates/README.md` — норма записи, храповик, четыре способа вранья |
 
 ## 1. Наше — применяется в работе

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

@@ -329,6 +329,91 @@ grep» — потому что мерили обход дерева, а не и
 Это ровно тот случай, когда своя запись законна, но раздел «готовый аналог» обязан назвать
 чужой инструмент и сказать, **почему не он**.
 
+## Разбор истории 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` пишется, **что именно проверено**: какой инструмент