agent-quality-kit 0.15.0 → 0.16.0

package/README.md

@@ -5,27 +5,56 @@
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
 [![checks](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
 [![MIT licence](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
-[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
-**Check whether a repository is ready to have its code written by AI coding agents — and turn
-the rules it promises to follow into commands with exit codes.**
+**A check that cannot fail looks exactly like a check that passes.**
+
+`|| true`, `continue-on-error: true`, a linter pointed at an empty directory, a test with no
+assertion, a hook nobody ever installed, a command your `AGENTS.md` names that no longer exists —
+every one of them prints a green tick. AQK plants a known defect into a **copy** of your code,
+runs the checks your repository **declares**, and says which of them noticed and which stayed
+silent.
 
-Your `AGENTS.md` says what the project promises. Nothing checks that those promises are true, or
-that the commands it lists even run. AQK is that missing layer: one command reads the repository,
-reports a level from AQK-0 to AQK-3, and names every guard that is missing.
+It never reads "nothing printed" as "nothing wrong". Three outcomes, never two:
+
+| `✔` | `✘` | `?` |
+|---|---|---|
+| ran and found nothing | a finding about the code | **the check itself failed** — fix the tooling, not the file it named while dying |
 
-And one step further than the tools next door: `probe` plants a known defect into a copy of your
-project and checks whether your **declared** guards actually go red. "Tests exist" and "tests
-catch" are different claims — readiness scores measure the first one.
+The third one is the whole point. Counting it as either of the other two is how a repository ends
+up protected by checks that cannot go red.
 
 ```bash
-npx agent-quality-kit doctor    # code already exists: your level and what to install
+npx agent-quality-kit doctor    # code already exists: what it declares, what nothing is watching
 npx agent-quality-kit start     # no code yet: day-zero guards, right away
 ```
 
+Here is the first run on a repository whose pipeline is green and whose checks cannot go red.
+Nothing declared, nothing installed, no config written — it read the project's own `package.json`:
+
+```text
+Checks you ALREADY have (3) — found in your own files, not invented:
+✘  test         npm test   ← package.json
+   cannot fail: the verdict is swallowed right in the script — «|| true»
+✔  lint         npm run lint   ← package.json
+✘  typecheck    npm run typecheck   ← package.json
+   proves nothing: the whole script is a printout — «echo 'todo: turn this on'»
+
+2 of them cannot go red. Declaring a check that cannot fail only makes the silence
+machine-readable — fix the command first, then declare it.
+```
+
 `doctor` only reads. It writes no file and sends nothing anywhere — safe to point at a repository
-you have decided nothing about yet. Nothing to install: `npx` fetches the package (574.1 kB, measured 2026-09-10 — nothing guards this number, so check it
-when it matters).
+you have decided nothing about yet. Nothing to install: `npx` fetches the package — **≈0.7 MB**,
+a number a machine re-checks on every run rather than our memory.
+
+For Claude Code there is a plugin: the repository's real state reaches the agent's context before
+its first action, plus two skills — whether the declared checks can actually fail, and what to fix
+first. Installable from our own marketplace, with nobody's approval to wait for:
+
+```bash
+/plugin marketplace add arsen-ask-lx/Agent_Quality_Kit
+/plugin install aqk@agent-quality-kit
+```
 
 The one exception, named here because it is the only one: with `--brief` (how the hooks run it)
 `doctor` asks the npm registry for its own latest version — **at most once a day, never in CI**,
@@ -109,6 +138,8 @@ aqk prompt              one task to paste into an agent: what to fix, in order,
 aqk vitals              is what the kit runs on wired up: gate tools, hooks, freshness
 aqk feedback            feedback to the author: a report from the last run and probe,
                         plus a prefilled link. No paths, no code; nothing is sent for you
+aqk feedback --send     send it in one command — with your own gh account, as a comment
+                        in an open discussion. Without the flag nothing ever leaves
 aqk doctor --run --brief  one line on success, the whole run on failure — for hooks
 aqk context --full      the same plus the command map and the rulebook verbatim (~7000
                         tokens against ~500: the price of an agent that does not guess)
@@ -148,7 +179,7 @@ $ npx agent-quality-kit doctor --run # runs them
         ./src/api/mailer.py:8:    print("sent", to)
   ✘  todo-without-task     exit 1
         ./src/web/app.js:1:// TODO: rewrite this
-  ✔  file-size-limit · entry-links-exist · complexity-limit
+  ✔  file-size-limit · deps-are-pinned · complexity-limit
 ```
 
 The failure text is written for an agent: it says **what exactly to do**. The exit code is for
@@ -195,6 +226,8 @@ gates:                     # what must pass — as commands, not as prose
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
 covers:                    # what a declared gate already holds — not counted as debt
   lint: [no-print-in-prod, swallowed-error]
+requires:                  # what a gate runs on, when the command does not show it
+  secrets-not-in-code: gitleaks
 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
@@ -224,6 +257,13 @@ catches things" are different claims, and the output says so out loud.
 
 ## Four levels
 
+[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
+
+**A level measures equipment, not quality.** It says which guards a repository has and has proven
+on samples — not that the code is good, and not that the guards caught anything in *your* files.
+That is what `probe` is for, and `doctor` prints what the level does **not** prove right under it.
+The badge above is this repository's own, kept honest by `aqk badge --check` in its pipeline.
+
 | Level | Required | What it proves |
 |---|---|---|
 | **AQK-0** | a manifest and an entry point | the tooling knows what to read |
@@ -353,7 +393,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.15.0
+    rev: v0.16.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
@@ -374,7 +414,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.15.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.16.0
   with:
     min: 1   # the build fails below AQK-1, or if any declared gate failed
 ```
@@ -596,6 +636,12 @@ aqk blob     # assembles GOD_AI.md out of kit/docs — to hand the guides to a c
 The file is **assembled, not stored**: edit the originals. A hand-edited copy drifts from its
 source within a week, and then nobody knows which one is real.
 
+A single gate is waited on for **five minutes**; past that it is "could not check", not
+"clean". Change it with `AQK_GATE_TIMEOUT` (seconds): `AQK_GATE_TIMEOUT=900 aqk doctor --run`.
+The default is not arbitrary — SonarQube waits exactly as long for its quality gate. There is
+deliberately no per-gate `timeout` field in the manifest: neither pre-commit nor lefthook has
+one, and a long check is more honestly declared as a separate command than allowed to hang.
+
 ## Contributing a gate
 
 The catalogue lives on other people's bruises. The procedure and the bar are in

package/README.ru.md

@@ -5,28 +5,57 @@
 [![npm](https://img.shields.io/npm/v/agent-quality-kit)](https://www.npmjs.com/package/agent-quality-kit)
 [![проверки](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/arsen-ask-lx/Agent_Quality_Kit/actions/workflows/ci.yml)
 [![лицензия MIT](https://img.shields.io/npm/l/agent-quality-kit)](LICENSE)
-[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
 
-**Проверить, готов ли репозиторий к тому, что код в нём пишет ИИ-агент — и превратить правила,
-которые проект обещает соблюдать, в команды с кодом возврата.**
+**Проверка, которая не может провалиться, выглядит точно так же, как проверка, которая прошла.**
+
+`|| true`, `continue-on-error: true`, линтер, направленный в пустой каталог, тест без единого
+утверждения, хук, который никто не поставил, команда из вашего же `AGENTS.md`, которой больше не
+существует, — каждое печатает зелёную галочку. AQK подсаживает заведомый дефект в **копию** вашего
+кода, запускает проверки, которые репозиторий **объявил**, и говорит, какая из них заметила, а
+какая промолчала.
 
-`AGENTS.md` говорит, что проект обещает. Никто не проверяет, правда ли это и запускаются ли
-вообще перечисленные там команды. AQK — тот самый недостающий слой: одна команда читает
-репозиторий, называет ступень от AQK-0 до AQK-3 и перечисляет каждого недостающего сторожа.
+Он никогда не читает «ничего не напечатано» как «ничего страшного». Три исхода, а не два:
+
+| `✔` | `✘` | `?` |
+|---|---|---|
+| отработала, чисто | находка о коде | **сама проверка не смогла** — чинить инструмент, а не файл, который она назвала, падая |
 
-И один шаг дальше, чем соседние инструменты: `probe` подсаживает заведомый дефект в копию вашего
-проекта и смотрит, покраснеет ли **объявленная** защита. «Тесты есть» и «тесты ловят» — разные
-утверждения, и оценки готовности меряют первое.
+Третий и есть весь смысл. Считать его одним из первых двух — так и получается репозиторий,
+защищённый проверками, которые не умеют покраснеть.
 
 ```bash
-npx agent-quality-kit doctor    # код уже есть: уровень и что поставить
+npx agent-quality-kit doctor    # код уже есть: что объявлено и чего не сторожит никто
 npx agent-quality-kit start     # кода ещё нет: сторожа дня 0 сразу
 ```
 
+Вот первый запуск на репозитории, где конвейер зелёный, а покраснеть не может ни одна проверка.
+Ничего не объявлено, ничего не поставлено, ни одного файла не записано — прочитан его же
+`package.json`:
+
+```text
+Проверки, которые у вас УЖЕ ЕСТЬ (3) — прочитаны в ваших файлах, не выдуманы:
+✘  test         npm test   ← package.json
+   не может провалиться: исход погашен прямо в скрипте — «|| true»
+✔  lint         npm run lint   ← package.json
+✘  typecheck    npm run typecheck   ← package.json
+   ничего не доказывает: всё тело скрипта — печать — «echo 'todo: turn this on'»
+
+из них 2 покраснеть не могут. Объявить проверку, которая не может провалиться, — значит
+сделать молчание машинно-читаемым. Сначала почините команду.
+```
+
 `doctor` только читает: ни одного файла не пишет и никуда ничего не отправляет — его можно
 направить на репозиторий, о котором ещё ничего не решено. Ставить ничего не нужно, `npx` скачает
-пакет сам (574.1 kB, замер 2026-09-10 — это число не сторожит никто, так что при случае
-перемерьте).
+пакет сам — **≈0,7 МБ**; это число сверяет машина при каждом прогоне, а не наша память.
+
+Для Claude Code есть плагин — состояние репозитория попадает в контекст агента до его первого
+действия, плюс два умения: «работают ли проверки» и «что чинить по порядку». Ставится из нашей
+же витрины, без ожидания чьего-либо одобрения:
+
+```bash
+/plugin marketplace add arsen-ask-lx/Agent_Quality_Kit
+/plugin install aqk@agent-quality-kit
+```
 
 Единственное исключение, и названо оно здесь именно потому, что единственное: с `--brief`
 (так его запускают хуки) `doctor` спрашивает у реестра npm свою последнюю версию — **не чаще
@@ -111,6 +140,8 @@ aqk prompt              одно задание для агента: что по
 aqk vitals              подключено ли то, чем комплект работает: инструменты, хуки, свежесть
 aqk feedback            отзыв автору: отчёт из последнего прогона и пробы плюс готовая
                         ссылка. Без путей и без кода; ничего не отправляет само
+aqk feedback --send     отправить его одной командой — вашей же учётной записью gh,
+                        комментарием в открытое обсуждение. Без флага не уходит ничего
 aqk doctor --run --brief  одна строка на успехе, весь прогон при провале — для хуков
 aqk context --full      то же плюс карта команд и свод правил дословно (≈7000 токенов
                         против ≈500 — плата за то, чтобы агент не догадывался)
@@ -151,7 +182,7 @@ $ npx agent-quality-kit doctor --run # запускает их
         ./src/api/mailer.py:8:    print("sent", to)
   ✘  todo-without-task     код 1
         ./src/web/app.js:1:// TODO: переписать
-  ✔  file-size-limit · entry-links-exist · complexity-limit
+  ✔  file-size-limit · deps-are-pinned · complexity-limit
 ```
 
 Текст отказа написан для агента: в нём сказано, **что именно сделать**. Код возврата — для
@@ -198,6 +229,8 @@ gates:                     # что обязано пройти — команд
   secrets-not-in-code: "bash gates/secrets-not-in-code/check.sh ."
 covers:                    # что уже держит объявленный гейт — в долг не пишется
   lint: [no-print-in-prod, swallowed-error]
+requires:                  # чем гейт работает, если по команде этого не видно
+  secrets-not-in-code: gitleaks
 samples:  gates            # красный и зелёный образец каждой записи
 ratchets: ratchets         # реестры долга: список может только укорачиваться
 probe: 100                 # раз во столько коммитов проба делается сама; 0 — не делать
@@ -227,6 +260,14 @@ aqk doctor --baseline   # ✔/✘ по пунктам, которые машин
 
 ## Четыре ступени
 
+[![AQK-3](https://img.shields.io/badge/AQK-3-2ea44f)](https://github.com/arsen-ask-lx/Agent_Quality_Kit)
+
+**Ступень меряет оснащённость, а не качество.** Она говорит, какие сторожа у репозитория есть и
+доказаны на образцах, — но не что код хорош и не что сторожа поймали хоть что-то в **ваших**
+файлах. Для этого есть `probe`, а `doctor` прямо под ступенью печатает, чего она **не**
+доказывает. Значок выше — наш собственный, и его правдивость держит `aqk badge --check` в
+конвейере.
+
 | Уровень | Требуется | Что доказано |
 |---|---|---|
 | **AQK-0** | манифест и точка входа | инструмент знает, что читать |
@@ -357,7 +398,7 @@ aqk badge --check  # в конвейере: код 1 в тот день, ког
 ```yaml
 repos:
   - repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit
-    rev: v0.15.0
+    rev: v0.16.0
     hooks:
       - id: aqk            # запускает объявленное; роняет коммит ниже AQK-1
       # - id: aqk-doctor   # только осмотр: уровень и чего не хватает, ничего не роняет
@@ -376,7 +417,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.15.0
+- uses: arsen-ask-lx/Agent_Quality_Kit@v0.16.0
   with:
     min: 1   # сборка падает ниже AQK-1 или если упал любой объявленный гейт
 ```
@@ -594,6 +635,12 @@ aqk blob     # собирает GOD_AI.md из kit/docs — чтобы разо
 Файл **собирается, а не хранится**: править надо оригиналы. Копия, которую правят руками, через
 неделю расходится с источником, и непонятно, какая настоящая.
 
+Один гейт ждут **пять минут**, дальше это «не смогли проверить», а не «чисто». Срок меняется
+переменной `AQK_GATE_TIMEOUT` (в секундах): `AQK_GATE_TIMEOUT=900 aqk doctor --run`. Умолчание
+взято не с потолка — столько же ждёт quality gate у SonarQube. Поля `timeout` у гейта в
+манифесте нет намеренно: его нет ни у pre-commit, ни у lefthook, а долгую проверку честнее
+объявить отдельной командой, чем разрешить ей висеть.
+
 ## Принести свой гейт
 
 Каталог живёт чужими шишками. Порядок и порог — в [`CONTRIBUTING.md`](CONTRIBUTING.md):

package/kit/docs/ai/index.md

@@ -26,6 +26,7 @@
 
 | Документ | О чём | Класс |
 |---|---|---|
+| [`operational-gates.md`](operational-gates.md) | актуальная карта OOM, N+1, Celery, метрик и нагрузки: что закрыто, что только видно и как подключать через AQK без дублей | PORTABLE |
 | [`agent-harness-playbook.md`](agent-harness-playbook.md) | чек-лист «День 0»: конфиги, линтеры, хуки, CI, Docker. Раздел 18 — дисциплина в каждой задаче | PORTABLE |
 | [`project-baseline.md`](project-baseline.md) | что обязано быть на любом проекте, чтобы работу можно было отдать машине. Назначение без названий инструментов | PORTABLE |
 | [`ai-sdlc.md`](ai-sdlc.md) | процесс по этапам: от «зачем» до эксплуатации. Отвечает «в каком порядке», а не «каким инструментом» | CURRENT |

package/kit/docs/ai/operational-gates.md

@@ -0,0 +1,275 @@
+# Эксплуатационные гейты из живого AI-проекта: что переносить, а что не притворять универсальным
+
+> Проверено по коду `audit_project` 15.09.2026, ссылки на первоисточники сверены 16.09.2026. Это актуальная карта практики, а не ручной
+> снимок production-метрик. Живые значения остаются в Prometheus, логах и отчётах прогонов.
+>
+> Главная граница: здесь описаны **намерения и устройство арбитров**. Реализация конкретного
+> Django/Celery/Compose-проекта остаётся в его репозитории и объявляется в `.aqk.yml` командой,
+> а не копируется в AQK.
+
+## Один вывод
+
+Зелёная фича ещё не означает зелёную систему. Query budget одной ручки, memory budget одной
+задачи и тест одного worker не отвечают на вопрос, выдержит ли одновременно работающий флот
+общую RAM, PostgreSQL, Redis, диск и очередь.
+
+Поэтому бюджетов всегда два:
+
+1. **локальный** — SQL, время, память и корректность одного endpoint/task;
+2. **системный** — p95, error rate, суммарный working set, очереди и OOM под смешанной нагрузкой.
+
+## Карта по факту
+
+| Область | Что действительно держит машина | Честная граница |
+|---|---|---|
+| N+1 | 21 тестовый файл и 63 вызова `assertNumQueries` / `django_assert_max_num_queries`; полный pytest блокирует рост известных бюджетов | нет требования, что **каждая новая** list/paginated-ручка получила budget-тест |
+| DirectPG N+1 | отдельный тест проверяет не только число запросов, но и отсутствие линейного роста на увеличенном наборе | это проектный арбитр, обычный Django-счётчик его не заменяет |
+| OOM после факта | `ContainerOOM` на росте `container_oom_events_total`; выражение имеет firing и quiet сценарии `promtool` | cAdvisor в основном описывает работающие контейнеры; история exited/restart требует отдельного источника |
+| Лимиты observability | тест разбирает Compose и держит сумму лимитов tier под явным капом | это кап одного tier, не бюджет всего production-флота и не резерв RAM хоста |
+| Celery topology | объявленные/используемые очереди сравниваются с `worker -Q` в production Compose | имена и структура конфигурации проектные |
+| Celery redelivery | `visibility_timeout` сравнивается с максимальным hard time limit и запасом | длинный timeout ухудшает скорость возврата работы после принудительной смерти worker |
+| Публичные метрики | publisher обязан попасть в реестр; быстрый pre-commit ловит забытое имя, pytest проверяет глубокую проводку | наличие имени не доказывает, что production реально его собирает |
+| Prometheus rules | синтаксис и выбранная семантика правил проверяются `promtool`; после deploy сверяется набор реально загруженных правил | не каждое правило уже имеет отдельные firing/quiet samples |
+| Скрипты-гейты | `check-gate-wiring.py` требует автоматический запуск либо честную запись в реестре ручных инструментов | «запускается» не означает «полезен»; это другой вопрос |
+| Ошибки и trace | GlitchTip, Sentry SDK, Loki/Alloy и `request_id` связывают исключение с окружением запроса | доступность самой цепочки также нуждается в heartbeat/alert |
+| Backup | расписание, ротация, метрика успеха, `BackupStale` и тесты скрипта | копия на том же сервере не переживёт потерю сервера; restore надо репетировать отдельно |
+
+## Что ещё только видно, но не закрыто
+
+Наличие графика или Telegram-alert не равно предотвращению.
+
+### Память
+
+- нет ранней полосы «контейнер долго держится выше доли своего лимита»;
+- нет отношения `sum(container working_set) / host RAM` для всего флота;
+- нет host-level RAM/swap/PSI прибора уровня node exporter;
+- нет долговечной истории OOM/restart для уже остановившихся контейнеров;
+- нет memory budgets для всех тяжёлых pytest-сценариев;
+- сумма отдельных потолков не является резервированием общей памяти.
+
+Последний пункт особенно важен. Docker ограничивает отдельный сервис, но несколько сервисов
+могут одновременно приблизиться к своим пределам и исчерпать хост. Поэтому static Compose gate
+и runtime fleet gate решают разные задачи; один нельзя выдавать за другой.
+
+### PostgreSQL и Redis
+
+Экспортёры есть, но нужны отдельные решения по сигналам:
+
+- насыщение соединений и ожидание PgBouncer;
+- длинные транзакции, deadlocks, temp bytes и блокировки;
+- память Redis broker при `noeviction`;
+- rejected writes, а не только evictions;
+- возраст старейшей работы и ожидаемое время разбора очереди, а не одна глубина.
+
+### Нагрузка
+
+- Python load harness измеряет p50/p95/p99 и RPS, но плохие числа сами не дают красный код;
+- k6 thresholds существуют лишь у отдельных ручных сценариев;
+- нет обязательного смешанного прогона HTTP + Celery + отчёты + документы + интеграции;
+- нет nightly/pre-release запуска;
+- нет регулярного soak для утечек, high-watermark процессов и накопления соединений.
+
+## Как строится честный OOM-контур
+
+Одного правила `any OOM` мало. Нужны пять независимых слоёв.
+
+### 1. Статические лимиты сервисов
+
+Production Compose задаёт `deploy.resources.limits.memory` или эквивалент. Проверка разбирает
+эффективную конфигурацию, а не ищет слово `memory` grep-ом. Для каждого обязательного сервиса
+должно быть ясно, почему лимит такой и каким замером он получен.
+
+### 2. Конфигурационный бюджет
+
+Сумма лимитов выбранного tier не растёт молча. Это храповик конфигурации, а не обещание, что RAM
+зарезервирована. Поднять кап можно только вместе с измерением хоста и записанной причиной.
+
+### 3. Runtime budget флота
+
+Под смешанной нагрузкой считается:
+
+```text
+max_over_time((sum(container_memory_working_set_bytes))[15m:1m]) / host_memory_bytes
+```
+
+Точный PromQL зависит от labels и источника host memory. Порог нельзя копировать вслепую; для
+малого сервера разумная стартовая красная полоса должна оставлять запас ядру, Docker, page cache
+и пикам PostgreSQL. В исследованном проекте рабочей гипотезой остаётся 70%, но она ещё не стала
+доказанным гейтом.
+
+### 4. Раннее предупреждение контейнера
+
+Устойчивое превышение доли лимита предупреждает до OOM. Рабочая гипотеза проекта — около 85%,
+но её надо откалибровать по пикам и шуму. Мгновенный spike и десять минут давления — разные
+события.
+
+### 5. OOM и restart после факта
+
+Рост `container_oom_events_total` — critical. Но исчезновение ряда остановленного контейнера не
+должно превратить аварию в тишину: Docker events/inspect или другой collector хранит exit reason,
+restart count и timestamp независимо от текущей жизни контейнера.
+
+### Доказательство правила
+
+Для alert нужны минимум два `promtool`-сценария:
+
+- counter вырос внутри окна → alert firing с ожидаемыми labels/annotations;
+- counter не растёт → alert отсутствует.
+
+Синтаксически корректное выражение `vector(0)` обязано сделать первый сценарий красным. Если вся
+батарея остаётся зелёной, семантика OOM не проверяется.
+
+## Как строится N+1-гейт
+
+Один статический поиск `select_related` ничего не доказывает. Арбитр должен наблюдать полный
+операционный путь.
+
+1. Создать больше одного связанного объекта; для list endpoint обычно нужны десятки строк.
+2. Выполнить настоящий HTTP-запрос или функцию задачи.
+3. Зафиксировать постоянный максимум SQL, а не `текущее число + 1`.
+4. Увеличить объём fixture и проверить, что число запросов не растёт линейно.
+5. Запускать тест в общей блокирующей батарее.
+
+Django официально предоставляет `assertNumQueries`. Для pytest допустима обёртка с верхним
+пределом, если она печатает выполненные запросы при превышении. Direct SQL, Trino и внешние базы
+нуждаются в своём счётчике — ORM-инструмент не видит их по построению.
+
+Честная граница: наличие двадцати одного budget-теста не доказывает покрытие двадцать второй ручки.
+Отдельный coverage-gate возможен только тогда, когда проект умеет машинно определить множество
+ручек, для которых budget обязателен. Проверять слово в имени теста недостаточно.
+
+## Два инварианта Celery
+
+### Очередь имеет потребителя
+
+Сопоставляются три факта:
+
+- очереди, объявленные в настройках;
+- очереди, используемые routes, task decorators и `apply_async`;
+- очереди, которые реально слушают production workers.
+
+Новая очередь без consumer красит CI. Документ или диаграмма не являются источником истины.
+
+### Доставка не опережает hard timeout
+
+Redis visibility timeout определяет, когда неacknowledged message возвращается в очередь. Если
+задача законно выполняется дольше, второй worker может получить её повторно. Проектный гейт
+сравнивает отношения настроек и fail-closed обрабатывает неразрешимые значения.
+
+Это не универсальная формула для всех Celery-систем: ETA/retry и принудительное завершение
+создают обратную цену слишком большого timeout. Инвариант должен учитывать модель задач проекта.
+
+## Метрика и алерт — это цепочка, а не файл
+
+Полный путь выглядит так:
+
+```text
+код публикует имя
+  → exporter его принимает
+  → Prometheus scrape видит ряд
+  → правило вычисляется правильно
+  → Alertmanager маршрутизирует
+  → человек получает сообщение
+  → runbook говорит, что делать
+```
+
+Для каждого шва нужен свой арбитр. Unit-test publisher не доказывает scrape. `promtool check`
+не доказывает смысл выражения. Тест выражения не доказывает, что production загрузил новый файл.
+После deploy полезна read-only сверка repo rule names с Prometheus API.
+
+## Нагрузочный гейт и soak
+
+Короткий mixed scenario должен иметь код возврата и одновременно держать:
+
+- error rate;
+- p95 ключевых пользовательских путей;
+- throughput или время разбора очередей;
+- суммарный working set флота;
+- отсутствие OOM/restart;
+- при необходимости соединения PostgreSQL и rejected writes Redis.
+
+Короткий прогон не ловит медленную утечку. Soak запускается отдельно и реже, с теми же
+инвариантами, но с проверкой тренда памяти, соединений и очередей во времени. Смешивать soak с
+каждым pre-push нельзя: дорогой гейт начнут обходить.
+
+## Где здесь агент
+
+Агент не должен решать, случилась ли аномалия. Сначала детерминированный detector:
+
+```text
+Prometheus rule или baseline script
+  → фильтрация и группировка события
+  → краткоживущий read-only агент
+  → гипотеза + evidence + confidence + связанный deploy
+  → issue / intent / merge request
+  → решение человека
+```
+
+По расписанию работает baseline script. Модель вызывается только по нарушению полосы. На первом
+этапе ей достаточно read-only доступа к Prometheus, Loki, error tracker и истории deploy; права
+на production DB, Docker socket, merge и произвольный runbook не нужны.
+
+## Как подключать это через AQK без дублей
+
+AQK-манифест объявляет **существующую команду проекта**:
+
+```yaml
+gates:
+  project-verify: "bash scripts/verify.sh"
+  prometheus-rules: "docker run --rm ... promtool test rules alerts_test.yml"
+groups:
+  code: [project-verify]
+  observability: [prometheus-rules]
+```
+
+Внутренние шаги `project-verify` не перечисляются второй раз в манифесте. При падении агрегатор
+обязан назвать конкретный шаг. Отдельным gate становится только команда, которую агрегатор
+честно не запускает.
+
+Один gate AQK получает не больше пяти минут. Если полный verifier проекта дольше, в манифесте
+нужен его быстрый блокирующий режим, а `--full` — отдельный прямой или CI-прогон. Иначе AQK будет
+честно возвращать «не смог проверить: timeout», но интеграция не станет рабочим локальным gate.
+
+Не надо:
+
+- копировать project-specific Python checks в `kit/gates`;
+- объявлять grep по словам `memory` или `assertNumQueries` доказательством;
+- указывать похожий каталог как `samples`, если структура AQK red/green там отсутствует;
+- повышать уровень AQK заглушками;
+- запускать `aqk init --force` поверх зрелого корпуса правил без review.
+
+Новая запись каталога AQK появляется после трёх доказательств: устойчиво опознаваемая конструкция,
+red/green samples и переносимый рецепт с понятной границей ложных срабатываний. До этого это
+методика или собственный gate проекта — и это честное состояние.
+
+## Порядок для нового проекта
+
+1. До кода записать измеримые AC: SQL, p95, error rate, memory, очередь, идемпотентность.
+2. Быструю детерминированную статику поставить в pre-commit.
+3. Query и task budgets поставить в обычный CI.
+4. Compose limits и alert rules проверять нативными валидаторами.
+5. Mixed load запускать nightly и перед релизом; soak — отдельно, например еженедельно.
+6. Любой OOM сделать красным исходом и сохранить причину после смерти контейнера.
+7. Только после стабилизации сигналов подключать read-only агента к нескольким critical alerts.
+
+## Официальные источники
+
+- [Django 5.2: `assertNumQueries`](https://docs.djangoproject.com/en/5.2/topics/testing/tools/#django.test.TransactionTestCase.assertNumQueries)
+- [Prometheus: unit testing rules через `promtool`](https://prometheus.io/docs/prometheus/latest/configuration/unit_testing_rules/)
+- [cAdvisor: Prometheus metrics, включая `container_oom_events_total`](https://github.com/google/cadvisor/blob/master/docs/storage/prometheus.md)
+- [Docker Compose: resource limits](https://docs.docker.com/reference/compose-file/deploy/#resources)
+- Docker про то, что сумма отдельных limits не гарантирует запас хоста — дословно:
+  «Using `--reserve-memory` and `--limit-memory` does not guarantee that Docker will not use more
+  memory on your host than you want», страница
+  [`docker service create`](https://docs.docker.com/reference/cli/docker/service/create/).
+  Якорь раздела не указан намеренно: страница собирается на стороне браузера, и проверить
+  существование якоря запросом нельзя — а ссылка на несуществующий якорь молча ведёт наверх.
+- [Celery Redis: visibility timeout и redelivery](https://docs.celeryq.dev/en/main/getting-started/backends-and-brokers/redis.html#visibility-timeout)
+
+## Финальный принцип
+
+> Сначала детерминированный сигнал и ограничение. Потом агент. Никогда наоборот.
+
+Повторившаяся ошибка должна оставлять после себя не ещё один абзац, а арбитр с кодом возврата.
+Если переносимого арбитра пока нет, граница называется вслух — текст не получает фальшивое имя
+«гейт».

package/kit/gates/_target.sh

@@ -0,0 +1,53 @@
+# Общий шов для проверок, судящих ПУТЬ, взятый из текста.
+#
+# ЗАЧЕМ ЭТОТ ФАЙЛ. Замеры 14-15 сентября 2026 по 290 чужим репозиториям нашли у нас двенадцать
+# ложных срабатываний. Разбор показал, что это не двенадцать ошибок, а ОДНА, повторённая
+# двенадцатью способами: мы судили строку как путь на диске, не зная, чем она разрешается.
+# Разрешало её то, чего у нас нет, — адрес на github.com, переменная окружения, генератор сайта,
+# соседний репозиторий вики, проза вокруг.
+#
+# Чинить такое по одному значит растить в каждом гейте свой список исключений; через три правки
+# списки разойдутся, и дважды пойманная беда вернётся через тот гейт, куда её не дописали.
+# Поэтому решение одно и здесь.
+#
+# ТРИ ИСХОДА, А НЕ ДВА — тот же договор, что у всего комплекта:
+#   disk        путь ведёт на файл в этом каталоге, судить можно
+#   unresolved  разрешается чем-то, чего у нас нет: МОЛЧАТЬ НЕЛЬЗЯ, но и обвинять нельзя
+#   skip        не путь вовсе (сеть, почта, якорь) — говорить не о чем
+
+# Якорь и строка запроса — не часть имени файла. `assets/x.gif?raw=1` лежит на диске как
+# `assets/x.gif`, `tutorial/#install` — это адрес страницы. Чистится ЗДЕСЬ, а не у зовущего:
+# иначе каждый гейт будет чистить по-своему, и один забудет.
+clean_target() {
+  T="${1%%#*}"
+  printf '%s' "${T%%\?*}"
+}
+
+# Возвращает слово исхода, а для unresolved — ещё и причину через двоеточие.
+classify_target() {
+  T="$1"
+  case "$T" in
+    ""|\#*) echo "skip"; return ;;
+    # ЛЮБАЯ СХЕМА, В ЛЮБОМ РЕГИСТРЕ. Замер 2026-09-15: `file://Users/...` и
+    # `Https://conventionalcommits.org` с заглавной H объявлены битыми файлами. Раньше узнавались
+    # только `http://` и `https://` строчными — и это была догадка о том, как люди пишут.
+    *://*|mailto:*|MAILTO:*) echo "skip"; return ;;
+    # Адрес почты целью ссылки без «mailto:». Замер: три таких объявлены битыми файлами.
+    *@*.*) echo "skip"; return ;;
+  esac
+  case "$T" in
+    # Путь, уходящий выше корня: так сам GitHub предлагает ссылаться на выпуски и задачи —
+    # `../../releases` считается от адреса файла в вебе. Проверено: страница отдаёт 200.
+    ../*) echo "unresolved:адрес на github.com" ;;
+    # Путь от корня САЙТА, а не репозитория.
+    /*) echo "unresolved:адрес на github.com" ;;
+    # Страница вики живёт в отдельном репозитории `<репо>.wiki`, которого мы не скачиваем.
+    wiki/*) echo "unresolved:вики в отдельном репозитории" ;;
+    # Путь с косой чертой на конце и страница `.html` — это адрес опубликованного сайта:
+    # mkdocs, docusaurus, pkgdown собирают их при публикации. Проверено: 200 на их сайтах.
+    */|*.html|*.htm) echo "unresolved:страницу собирает генератор сайта" ;;
+    # Нераскрытая переменная: значение задаётся снаружи.
+    *'$'*) echo "unresolved:путь зависит от переменной" ;;
+    *) echo "disk" ;;
+  esac
+}